 $ type release.mem











                            VAX-11 DATATRIEVE 
                            Installation Guide/Release Notes

                            Order No. AA-K083D-TE




                            ---------------------------------------------------




                            December 1982

                            This manual contains the installation procedure and
                            release notes for VAX-11 DATATRIEVE.












                            OPERATING SYSTEM 
                            AND VERSION:      VMS                  V3 or higher
                            SOFTWARE VERSION: VAX-11 DATATRIEVE    V1.3




                            digital equipment corporation, maynard, massachusetts









                                               1






        The information in this document is subject to change without notice
        and should not be construed as a commitment by Digital Equipment
        Corporation.  Digital Equipment Corporation assumes no responsibility
        for any errors that may appear in this document.

        The software described in this document is furnished under a license
        and may be used or copied only in accordance with the terms of such
        license.

        No responsibility is assumed for the use or reliability of software on
        equipment that is not supplied by DIGITAL or its affiliated companies.


        Copyright (C) 1982 by Digital Equipment Corporation.  All rights
        reserved.


        The following are trademarks of Digital Equipment Corporation:

             DEC                   MASSBUS               UNIBUS
             DECmate               PDP                   VAX
             DECsystem-10          P/OS                  VMS
             DECsystem-20          Professional          VT
             DECUS                 Rainbow               Work Processor
             DECwriter             RSTS                                  
             DIBOL                 RSX                                   




























                                          ii























                                       CONTENTS

                1.0     PURPOSE OF THIS BOOK . . . . . . . . . . . . . . . iii
                2.0     CONVENTIONS USED IN THIS MANUAL  . . . . . . . . .  iv


        CHAPTER 1       VAX-11 DATATRIEVE INSTALLATION PROCEDURE

                1.1     SYSTEM REQUIREMENTS  . . . . . . . . . . . . . . . 1-3
                1.2     START THE INSTALLATION PROCEDURE . . . . . . . . . 1-4
                1.2.1     Required Privileges to Complete the Installation 1-4
                1.2.2     Setting the Default Directory  . . . . . . . . . 1-4
                1.2.3     Invoking the Command Procedure VMSUPDATE . . . . 1-5
                1.3     MOUNT DISTRIBUTION MEDIA . . . . . . . . . . . . . 1-6
                1.4     ANSWERING QUESTIONS DURING THE INSTALLATION  . . . 1-7
                1.4.1     If the Target Rooted Device IS NOT the System 
                          Rooted Device  . . . . . . . . . . . . . . . . . 1-9
                1.4.2     If the Target Rooted Device IS the System 
                          Rooted Device  . . . . . . . . . . . . . . . .  1-10
                1.5     REPLACE STANDARD CONSOLE MEDIUM  . . . . . . . .  1-12


        CHAPTER 2       USER ENVIRONMENT TEST PACKAGES

                2.1     THE DATATRIEVE UETP  . . . . . . . . . . . . . . . 2-1
                2.2     THE DATATRIEVE-FMS UETP  . . . . . . . . . . . . . 2-5
                2.3     THE DATATRIEVE GRAPHICS UETP . . . . . . . . . . . 2-7
                2.4     THE DATATRIEVE/DBMS UETP . . . . . . . . . . . . . 2-9


        CHAPTER 3       RELEASE NOTES FOR VAX-11 DATATRIEVE

                3.1     INTRODUCTION . . . . . . . . . . . . . . . . . . . 3-1
                3.2     NEW FEATURES   . . . . . . . . . . . . . . . . . . 3-2
                3.2.1     The Logical Name DTR$DATE_INPUT  . . . . . . . . 3-2
                3.2.2     A Third Concatenation Expression . . . . . . . . 3-2
                3.2.3     The CROSS Clause . . . . . . . . . . . . . . . . 3-3
                3.2.4     The EDIT Command . . . . . . . . . . . . . . . . 3-3
                3.2.5     SORT   . . . . . . . . . . . . . . . . . . . . . 3-4
                3.2.6     The VAX-11 Common Data Dictionary  . . . . . . . 3-4
                3.2.6.1     The Default Dictionary Directory . . . . . . . 3-4
                3.2.6.2     The SET DICTIONARY Command . . . . . . . . . . 3-4
                3.2.6.3     The DEFINE DICTIONARY Command  . . . . . . . . 3-5
                3.2.6.4     The SHOW PRIVILEGES Command  . . . . . . . . . 3-5
                3.2.6.5     The DEFINEP Command  . . . . . . . . . . . . . 3-5
                3.2.7     The Startup Command File: DTR$STARTUP  . . . . . 3-5
                3.2.8     User-defined Synonyms: DTR$SYNONYM . . . . . . . 3-6
                3.2.9     Domain Tables  . . . . . . . . . . . . . . . . . 3-6
                3.2.10    Additions to Dictionary Tables . . . . . . . . . 3-7
                3.2.11    Miscellaneous Syntax Changes . . . . . . . . . . 3-7
                3.2.12    Qualified Field Names  . . . . . . . . . . . . . 3-7



                                         iii























                3.2.13    Missing Values . . . . . . . . . . . . . . . . . 3-8
                3.2.13.1    The MISSING VALUE Clause . . . . . . . . . . . 3-8
                3.2.13.2    The MISSING Relational Operator  . . . . . . . 3-8
                3.2.13.3    Missing Values in Statistical Functions  . . . 3-8
                3.2.13.4    Edit string for Missing Values   . . . . . . . 3-9
                3.2.14    The DEFAULT VALUE Clause . . . . . . . . . . . . 3-9
                3.2.15    FROM Value Expressions . . . . . . . . . . . . . 3-9
                3.2.16    The DROP Statement . . . . . . . . . . . . . .  3-10
                3.2.17    Extensions to the SELECT Statement . . . . . .  3-10
                3.2.18    The RUNNING TOTAL and RUNNING COUNT Statistical 
                          Functions  . . . . . . . . . . . . . . . . . .  3-10
                3.2.19    The Standard Deviation Function  . . . . . . .  3-10
                3.2.20    The EXTRACT ALL Command  . . . . . . . . . . .  3-11
                3.2.21    New Edit strings . . . . . . . . . . . . . . .  3-11
                3.2.22    The SET SEARCH Command . . . . . . . . . . . .  3-11
                3.2.23    The READY Command  . . . . . . . . . . . . . .  3-12
                3.2.24    The VAX-11 DATATRIEVE Call Interface . . . . .  3-12
                3.2.25    User-defined Functions . . . . . . . . . . . .  3-12
                3.2.26    The Keyword USAGE and the USAGE Clause . . . .  3-13
                3.2.27    The PLOT Command . . . . . . . . . . . . . . .  3-13
                3.2.28    The Distributed Data Manipulation Facility . .  3-13
                3.2.29    VAX-11 DATATRIEVE Support for VAX-11 FMS   . .  3-14
                3.2.30    VAX-11 DATATRIEVE Support of VAX-11 DBMS   . .  3-15
                3.2.31    LIST Statement . . . . . . . . . . . . . . . .  3-15
                3.2.32    The SHOW SET_UP Command  . . . . . . . . . . .  3-16
                3.3     COMPATIBILITY WITH DATATRIEVE-11 . . . . . . . .  3-17
                3.3.1     Field Alignment  . . . . . . . . . . . . . . .  3-17
                3.3.2     Dictionary Commands  . . . . . . . . . . . . .  3-18
                3.3.3     DEFINE DICTIONARY  . . . . . . . . . . . . . .  3-18
                3.3.4     Underscore and Hyphen  . . . . . . . . . . . .  3-18
                3.3.5     Invalid Picture Strings  . . . . . . . . . . .  3-18
                3.3.6     Spaces in Numeric Data . . . . . . . . . . . .  3-19
                3.3.7     Leading Spaces in Dictionary Tables  . . . . .  3-19
                3.4     TUNING VAX-11 DATATRIEVE PERFORMANCE . . . . . .  3-20
                3.4.1     Installing the VAX-11 DATATRIEVE Images as 
                          Shareable  . . . . . . . . . . . . . . . . . .  3-20
                3.4.2     Adjusting Working Set Quota  . . . . . . . . .  3-21
                3.5     DOCUMENTATION OMISSIONS AND CHANGES  . . . . . .  3-22
                3.5.1     Exponential Constants  . . . . . . . . . . . .  3-22
                3.5.2     BEFORE and AFTER Keywords  . . . . . . . . . .  3-22
                3.5.3     Selected Records in Sorted Collections . . . .  3-23
                3.5.4     Additional Entry Point to Callable Interface .  3-23
                3.5.5     Collection Size  . . . . . . . . . . . . . . .  3-23
                3.6     RESTRICTIONS . . . . . . . . . . . . . . . . . .  3-24
                3.6.1     Call Interface Options . . . . . . . . . . . .  3-24
                3.6.2     Forms  . . . . . . . . . . . . . . . . . . . .  3-24
                3.6.3     Remote Domains . . . . . . . . . . . . . . . .  3-26
                3.6.4     RMS Key Optimization . . . . . . . . . . . . .  3-27
                3.6.5     DBMS Optimization  . . . . . . . . . . . . . .  3-28
                3.6.6     Recursive Procedures . . . . . . . . . . . . .  3-28
                3.6.7     Inter-Domain Validation and Virtual Expressions 3-29



                                          iv























                3.7     USAGE NOTES  . . . . . . . . . . . . . . . . . .  3-30
                3.7.1     Using VAX-11 DATATRIEVE from a DCL Command File 3-30
                3.7.2     Very Long Input Lines  . . . . . . . . . . . .  3-30
                3.7.3     Arithmetic Accuracy  . . . . . . . . . . . . .  3-31
                3.7.4     Field Name Resolution on a CROSS . . . . . . .  3-32
                3.7.5     Remote DBMS Domains  . . . . . . . . . . . . .  3-33
                3.8     DIFFERENCES SINCE VAX-11 DATATRIEVE V1.2 . . . .  3-34
                3.8.1     Callable DATATRIEVE  . . . . . . . . . . . . .  3-34
                3.8.1.1     Varying String Descriptors . . . . . . . . .  3-34
                3.8.1.2     Blank Substitutions  . . . . . . . . . . . .  3-34
                3.8.2     Repair of Date Bugs  . . . . . . . . . . . . .  3-34
                3.8.2.1     Missing Values for Dates   . . . . . . . . .  3-34
                3.8.2.2     Date Arithmetic  . . . . . . . . . . . . . .  3-35
                3.8.2.3     Optimizing the Conversion from Text to Dates  3-35
                3.8.3     Standard Deviation is Fixed  . . . . . . . . .  3-36
                3.8.4     Limits Increased . . . . . . . . . . . . . . .  3-36
                3.8.5     Adding or Changing Domains with Key Fields . .  3-36
                3.8.6     OCCURS DEPENDING . . . . . . . . . . . . . . .  3-36
                3.8.7     Optimization of the OR Boolean.  . . . . . . .  3-37
                3.8.8     Retrieving Domain Tables from the CDD  . . . .  3-37
                3.8.9     Recursive Virtual Expressions  . . . . . . . .  3-37
                3.8.10    Report Writer  . . . . . . . . . . . . . . . .  3-37
                3.8.11    Ports  . . . . . . . . . . . . . . . . . . . .  3-38
                3.8.12    Miscellaneous  . . . . . . . . . . . . . . . .  3-38
                3.9     VAX-11 DATATRIEVE DATA TYPES . . . . . . . . . .  3-39


        APPENDIX A      QXTR: THE DATATRIEVE-11 EXTRACT PROGRAM


























                                          v





























        PREFACE






        1.0  PURPOSE OF THIS BOOK

        This manual is designed to guide the user in the installation of
        VAX-11 DATATRIEVE and any of the appropriate user environment test
        packages (UETPs).  It also contains information pertinent to this
        release regarding:

              o  New features

              o  Compatibility with DATATRIEVE-11

              o  Tuning the performance of VAX-11 DATATRIEVE

              o  Documentation omissions and changes

              o  Restrictions

              o  Usage notes

              o  VAX-11 DATATRIEVE data types





















                                          vi























        2.0  CONVENTIONS USED IN THIS MANUAL

        Examples of DATATRIEVE commands and statements are printed in a dot
        matrix typeface.  The DATATRIEVE or VAX/VMS output lines displayed on
        your terminal are printed in black.  The commands and statements you
        enter from your terminal are printed in red.

        Symbols and conventions used in syntax formats:


        UPPERCASE WORDS     Uppercase words in syntax formats and in the text
                            are DATATRIEVE keywords.

        lowercase words     Lowercase words in syntax formats are generic
                            terms that indicate entries you must provide.

        { }                 Braces in syntax formats mean you must choose one,
                            but no more than one, of the enclosed entries.

        [ ]                 Brackets in syntax formats mean you have the
                            option of choosing one, but no more than one, of
                            the enclosed entries.

        ...                 A horizontal ellipsis in syntax formats means you
                            have the option of repeating the preceding element
                            of the syntax format.

        .                   A vertical ellipsis in syntax formats means you
        .                   have the option of repeating the element of the
        .                   syntax format on the preceding line.

        " "                 These quotation marks are called double quotation
                            marks.

        ' '                 These quotation marks are called single quotation
                            marks.




















                                          7





























                                      CHAPTER 1

                       VAX-11 DATATRIEVE INSTALLATION PROCEDURE



        To install VAX-11 DATATRIEVE you must have VAX/VMS Version 3 on your
        system.

        The installation procedure for VAX-11 DATATRIEVE allows you to install
        VAX-11 DATATRIEVE on the system rooted device or on a target rooted
        device that is not the system rooted device.  A "rooted device" is a
        new directory concept introduced with VAX/VMS Version 3.0, referring
        to a device and directory combination.  See the VAX-11 RSX-11M/User's

                                                        ______ ______________
        Guide for more information on rooted devices.  The target of the

        _____
        installation is either the system rooted device (the logical device
        SYS$SYSROOT) or some other rooted device.

        If the target rooted device is not the system rooted device, you
        cannot run the User Environment Test Packages (UETPs) for DATATRIEVE.
        Chapter 2 explains the UETPs.  You should run the UETPs after you have
        bootstrapped, establishing the target rooted device as a system rooted
        device.  See the VAX/VMS System Management and Operations Guide for

                         _______ ______ __________ ___ __________ _____
        more information on bootstrapping using the target rooted device.

        Your Version 1.3 installation kit consists of one console medium
        (flexible diskette or TU58 DECtape) and one magnetic tape or disk
        pack.  These media make obsolete the distribution media for previous
        versions of VAX-11 DATATRIEVE (V1.0, V1.1, and V1.2).

        Here are the steps for installing VAX-11 DATATRIEVE:

        1.  Make sure that system requirements are met.

        2.  Log in under a privileged account.

        3.  Set your default UIC to [1,4].

        4.  Set your default rooted device to the target rooted device.

        5.  Set your default directory to [SYSUPD].






                                         1-1

















        VAX-11 DATATRIEVE INSTALLATION PROCEDURE


        6.  Type @VMSUPDATE.

        7.  Replace the standard console diskette or TU58 with the flexible
            diskette or TU58, VAXDTR1, from the installation kit.

        8.  Mount the magnetic tape or disk pack that comes with the
            installation kit.

        9.  Respond to questions as the installation command procedure sends
            them to your terminal.

        When you have installed VAX-11 DATATRIEVE, the following message
        displays on the terminal:

           Installation of VAX-11 DATATRIEVE is complete.

        VAX-11 DATATRIEVE is layered on many shared images that are charged
        against the user's open file limit.  To run DATATRIEVE successfully,
        DIGITAL recommends an open file limit (the FILLM parameter) of 30.  If
        you have a large application that uses many files, you may have to
        increase this value.  The failure that occurs is not graceful if you
        exhaust the open file limit when starting the DTR32 image.  You may
        get a meaningless display on the terminal, or a "Quota exceeded"
        message without further explanation.

        You may need to be concerned with the overall number of locks in the
        system and the ENQLM of individual users.  RMS and CDD both are
        consumers of locks.  An ENQLM of about 200 is sufficient for most
        activity, including running the DATATRIEVE UETPs.



























                                         1-2

















                                      VAX-11 DATATRIEVE INSTALLATION PROCEDURE


        1.1  SYSTEM REQUIREMENTS

        You must have Version 3.0 or higher of VAX/VMS to install VAX-11
        DATATRIEVE.  If you have an earlier version of VAX/VMS, you must
        install the most recent version of VAX/VMS before you can install
        VAX-11 DATATRIEVE.

        You must install the VAX-11 Common Data Dictionary before you can
        install VAX-11 DATATRIEVE.  See the VAX-11 Common Data Dictionary

                                            ______ ______ ____ __________
        Installation Guide for information on installing the VAX-11 Common

        ____________ _____
        Data Dictionary.  If you want to install VAX-11 DATATRIEVE and VAX-11
        DBMS, then you should install the products in the following order:

        1.  VAX-11 Common Data Dictionary

        2.  VAX-11 DBMS

        3.  VAX-11 DATATRIEVE

        The SYSGEN parameter PROCSECTCNT determines the maximum number of
        image sections that any one image can use.  The default number for
        PROCSECTCNT is 20.  The number of image sections for the VAX-11
        DATATRIEVE task image is 31 without DBMS, and 40 with DBMS.  This
        means that to run VAX-11 DATATRIEVE on a system, the system manager
        must set the PROCSECTCNT to at least 31 or 40.  If PROCSECTCNT is set
        to a lower value, you should set PROCSECTCNT to 31 or 40, and then
        reboot the system before installing VAX-11 DATATRIEVE.

        You need at least 4000 free blocks on the target rooted device.  If
        you run the VAX-11 DATATRIEVE/DBMS UETP, you must have 5100 free
        blocks.  The installation command procedure copies 41 files from the
        kit, and creates the files DTRSHR.EXE, DTR32.EXE, DDMF.EXE, OWNER.DAT,
        and YACHTS.DAT.  These files take up about 4000 blocks.  The
        DATATRIEVE/DBMS UETP creates files that take up an additional 1100
        blocks.  Thus, to install VAX-11 DATATRIEVE and run the
        DATATRIEVE/DBMS UETP, you must have 5100 free blocks on the target
        rooted device.



















                                         1-3

















        VAX-11 DATATRIEVE INSTALLATION PROCEDURE


        1.2  START THE INSTALLATION PROCEDURE

        Log in under a privileged account, such as the system manager's
        account.  If your default UIC is not [1,4], then change it to [1,4].



        1.2.1  Required Privileges to Complete the Installation

        Several privileges are required to successfully complete the
        installation.  These privileges are:

              o  BYPASS

              o  CMKRNL

              o  DETACH

              o  EXQUOTA

              o  NETMBX

              o  OPER

              o  PRMGBL

              o  PRMMBX

              o  PSWAPM

              o  SYSGBL

              o  SYSNAM

              o  SYSPRIV

              o  WORLD




        1.2.2  Setting the Default Directory

        If your target rooted device is the system rooted device, set your
        default directory to SYS$UPDATE.

        If your target rooted device is not the system rooted device, set your
        default device to the target rooted device and set your default
        directory to [SYSUPD].  For example:

           $ ASSIGN __DBA0:[SYS0.] DTR$DEVICE
           $ SET DEFAULT DTR$DEVICE:[SYSUPD]




                                         1-4

















                                      VAX-11 DATATRIEVE INSTALLATION PROCEDURE


        Note that two underscores are required in front of the device

                  ___
        specification.  In addition, the directory [SYS0.] must have a period
        at the end.  This establishes the root directory.  All files created
        in the installation are placed in subdirectories branching from this
        root directory.



        1.2.3  Invoking the Command Procedure VMSUPDATE

        Invoke the command procedure VMSUPDATE with the command:

           $ @VMSUPDATE 

        The system's installation command procedure (VMSUPDATE) prints the
        following message on the terminal:

           This command procedure performs VAX/VMS software updates and 
           optional software installations for VAX/VMS Release 3.
           During this sequence, the standard console medium will not 
           be present in the console drive. Therefore, the system may
           be vulnerable to power failure or other fatal crash. If a
           system crash should occur during this period the update
           sequence can be restarted at the beginning of the first
           incomplete update.

           Dismount the current console medium.

           Please place the first volume in the console drive.

        If the console medium is not mounted, you receive a device-not-mounted
        message, which you should ignore.
























                                         1-5

















        VAX-11 DATATRIEVE INSTALLATION PROCEDURE


        1.3  MOUNT DISTRIBUTION MEDIA

        Remove the console medium.  If you are using flexible diskettes, note
        the direction the console diskette is facing.  Diskettes from the
        distribution kit must be inserted in the drive so they face the same
        direction.  (The label is on the front side of the diskette.) Place
        the first medium, VAXDTR1, into the drive, and answer Y to the query:

           Are you ready to continue?

        After you respond Y to this query, the system sends you a message that
        VAXDTR1 is mounted on the console device.  Then the console medium is
        read, and the following messages are sent to the terminal:

           You must have Version 3 of VAX/VMS to install VAX-11 DATATRIEVE.
           If you have an earlier version of VMS, you must install the most 
           recent version of VMS before you can install VAX-11 DATATRIEVE.

           The VAX-11 DATATRIEVE installation kit consists of 2 media:

                   o One console medium (flexible diskette or TU58 DECtape)
                   o An auxiliary medium (mag tape or disk pack)

           For the following question, respond with the device on which
           the auxiliary medium is to be mounted (MT1:, DMA0:, etc.).
           Please include the colon (:) following the device name.

           What is the device name for the auxiliary medium? (DDCU:):

        Respond with the appropriate device name.  The system tries to
        allocate the device and sends a message to the terminal informing you
        whether the device has been allocated.  If the system is unable to
        allocate the device, the command procedure asks for the device name
        again.

        The following query is then sent to your terminal:

           Is the auxiliary medium ready to be mounted? [Y/N]:

        When you have mounted the auxiliary medium, respond Y to this query.
        After you respond, the system informs you that the device has been
        mounted.

        If you do not have sufficient privileges to continue, the system sends
        you a message indicating the necessary privileges.  You must obtain
        the privileges before you can continue with the installation.

        All of the files on the auxiliary medium are now copied onto the
        target rooted device.  This takes several minutes.







                                         1-6

















                                      VAX-11 DATATRIEVE INSTALLATION PROCEDURE


        1.4  ANSWERING QUESTIONS DURING THE INSTALLATION

        After the last console medium has been mounted and its files have been
        copied to the target rooted device, the following messages are sent to
        the terminal:

           This procedure checks to see if the Common Data Dictionary (CDD) has
           already been installed.  If CDD is not installed, the installation
           command procedure aborts and you must install CDD before you can 
           proceed with the DTR installation.  

           Do you wish to proceed with installation? [Y/N]:

        If you answer N, the installation procedure halts and VAX-11
        DATATRIEVE is not installed.  If you answer Y, the installation
        continues.  The installation command procedure checks whether VAX-11
        DBMS is installed on the rooted device.  If VAX-11 DBMS is not
        installed, the following message is sent to the terminal:

           You do not have VAX-11 DBMS installed on your system.  A dummy image
           file, DBMSHR.EXE, is being installed in SYS$LIBRARY.

        The installation command procedure now checks for the files
        [SYSLIB]DTRFND.MAR and DTRFUN.OLB.  These files are used for defining
        functions.  If these files are not present, the installation command
        procedure copies DTRFND.MAR and DTRFUN.OLB from the installation kit
        to [SYSLIB].  Whether the files are present before the current
        installation or are newly copied, the installation command procedure
        recompiles DTRFND.MAR to use the new version of the MACRO library,
        DTRFUNLIB.MLB.  If there is an error in the compilation of the
        existing DTRFND.MAR, then that DTRFND.MAR is renamed DTRFNDERR.MAR and
        the DTRFND.MAR from the installation kit is copied to [SYSLIB],
        compiled, and replaced in DTRFUN.OLB.























                                         1-7

















        VAX-11 DATATRIEVE INSTALLATION PROCEDURE


        The installation command procedure then builds the shareable images.
        This takes from 4 to 10 minutes, depending on how busy your system is.
        At the end of this period, the following message is sent to the
        terminal:

           If you wish, you may now have all files that were created by this 
           installation procedure PURGED in the various accounts where they
           were created.  No files are purged except those created in this
           installation.

           Do you wish to purge the installation files? [Y/N]:

        If you wish to purge the installation files, respond with Y.  After
        you respond, this message is sent to the terminal:

           You may optionally keep the VAX-11 DATATRIEVE object library in 
           SYS$LIBRARY.  If the object library is retained on disk, you may
           rebuild VAX-11 DATATRIEVE without reinstalling this kit. A
           rebuild is required if a user function is added to VAX-11 DATATRIEVE.

           A rebuild may be required for any of these events:

               o  VAX-11 DBMS is installed or patched
               o  A new version of the CDD is installed or patched
               o  A new version of Run-Time Library is installed  

           If the object library is retained, VAX-11 DATATRIEVE can be rebuilt 
           with the commands:

               SET DEF SYS$LIBRARY:
               @DTR32BLD

           Do you wish to leave the DATATRIEVE library on-line? [Y/N]: 

        To keep the DATATRIEVE library on-line, respond with Y.  After you
        respond to this query, the following message is sent to the terminal:

           This completes the basic installation of VAX-11 DATATRIEVE.
           The remainder of the installation consists of:

                   o Defining the DECnet object number for Distributed 
                     DATATRIEVE if necessary
                   o Loading the DATATRIEVE VT125 plot definitions
                   o Running the User Environment Test Packages for
                     DATATRIEVE

           This portion of the installation can be done only if the
           target rooted device is the system rooted device.  That is, if 
           you are building VAX-11 DATATRIEVE on a rooted device that is not
           the system rooted device, then you must now end the installation
           of VAX-11 DATATRIEVE.

           Do you wish to continue with installation? [Y/N]:



                                         1-8

















                                      VAX-11 DATATRIEVE INSTALLATION PROCEDURE


        If the target rooted device is not the system rooted device of your
        system, answer N.  Section 1.4.1 describes the rest of the
        installation if you answer N.

        If you are installing VAX-11 DATATRIEVE on your own system rooted
        device, answer Y.  Section 1.4.2 describes the rest of the
        installation if you answer Y.



        1.4.1  If the Target Rooted Device IS NOT the System Rooted Device

        After you answer N, the installation command procedure sends the
        following messages to the terminal:

           After you have booted using the target rooted device,
           be sure to run the VAX-11 DATATRIEVE User Environment 
           Test Package (UETP). At that time, enter these commands:

               $ SET DEFAULT SYS$SYSROOT:[SYSTEST.DTR32]
               $ RUN SYS$SYSTEM:DTR32 
               DTR> @DTR.TST

           Installation of VAX-11 DATATRIEVE is complete.

           For best performance, the system startup file [SYSMGR]SYSTARTUP.COM
           should be modified to install the images DTRSHR.EXE and DTR32.EXE.
           This can be done by adding the following:

                   $ RUN SYS$SYSTEM:INSTALL
                   INSTALL> SYS$SHARE:DTRSHR/OPEN/SHARE
                   INSTALL> DTR32/OPEN/SHARE

           For best performance in environments where the distributed features 
           of VAX-11 DATATRIEVE is anticipated, the system startup file
           [SYSMGR]STARTUP.COM should be modified to install the image DDMF.EXE.


           This can be done by adding the following:

                   $RUN SYS$SYSTEM:INSTALL
                   INSTALL> DDMF/OPEN/SHARE

        After you have booted using the target rooted device, do the
        following:

        1.  If you have DECnet installed and you wish to have a DATATRIEVE
            Remote Server on your machine, define the DECnet object number for
            Distributed DATATRIEVE (DDMF).  A DATATRIEVE Remote Server allows
            you to access domains on your system from any system on your
            network that has VAX-11 DATATRIEVE.  You must specify the network
            address of your system.  If you want to be able to omit username
            and password from the network address specification, create a
            default file such as [DECNET] on your system for the DDMF object
            you define.  This account should have the same file limit and



                                         1-9

















        VAX-11 DATATRIEVE INSTALLATION PROCEDURE


            working set quota parameters as any other account that uses
            DATATRIEVE.  You should also make sure that remote domains you
            want to access specify fully qualified filenames.

            To define the DECnet object number for DDMF, run NCP and use the
            DEFINE command.  The local object name is DDMF, the number is 30,
            the file name is DDMF, and no privileges are required.  For
            information about NCP, refer to the DECnet-VAX System Manager's

                                                __________ ______ _________
            Guide.

            _____

        2.  If you want to use the DATATRIEVE VT125 graphics package, load the
            VT125 plot definitions into the CDD.  There have been some changes
            in the definitions since the last version, so you should load the
            latest versions of the plot definitions.  Use the following
            commands to load the definitions:

               $ SET DEFAULT [SYSTEST.DTR32]
               $ RUN SYS$SYSTEM:DTR32

               DTR> @DTRPLOTS

        3.  Run the DATATRIEVE UETP (see Section 2.1).

        4.  Run the DATATRIEVE-FMS UETP (see Section 2.2).

        5.  Run the DATATRIEVE Graphics UETP (see Section 2.3).

        6.  If VAX-11 DBMS is installed, run the DATATRIEVE/DBMS UETP (see
            Section 2.4).




        1.4.2  If the Target Rooted Device IS the System Rooted Device

        After you answer Y to continue installation, the installation command
        procedure uninstalls the images DTRSHR and DTR32 if they are already
        present.  The following message is sent to the terminal:

           Ignore the message "known file not found".

        If either DTRSHR or DTR32 has not been previously installed, then the
        message "known file not found" is sent to the terminal.  Next the
        installation command procedure checks whether DECnet is installed.  If
        DECnet is installed, the following message is sent to the terminal:

           Before another VAX can access the DATATRIEVE Remote Server
           on your system, the DECnet object number for Distributed
           DATATRIEVE (DDMF) must be defined.  

           Do you wish to have the object number for DDMF defined? [Y/N]:

        If you choose to define the object number for DDMF yourself, answer N.



                                         1-10

















                                      VAX-11 DATATRIEVE INSTALLATION PROCEDURE


        If you answer Y, the command procedure defines the DECnet object
        number for DDMF to be 30.

        After the installation, you may want to create a default account such
        as [DECNET] for the object you define.  This lets remote users omit
        username and password from the network address specification when
        accessing domains on your node.  The account should have the same file
        limit and working set quota parameters as any other account that uses
        DATATRIEVE.  You should also make sure that remote domains you want to
        access specify fully qualified filenames.

        When you have answered the question about DDMF, the following message
        is sent to the terminal:

           VAX-11 DATATRIEVE contains graphics support for the VT125 terminal.
           In order to use the graphics features, it is necessary to load the
           DATATRIEVE plot definitions into the CDD. 

           The plot definitions have been changed for this version. Even if
           you have an earlier version in the CDD, you should load the plot 
           definitions now to update your software.

           Do you wish to load the VT125 plot definitions? [Y/N]:

        If you answer Y, the installation command procedure loads the VT125
        plot definitions into the CDD.  The plot definitions display on the
        terminal as they are loaded into the CDD.  The next message sent to
        the terminal concerns the User Environment Test Package for
        DATATRIEVE:

           If you wish, you may run the User Environment Test Package (UETP) 
           for VAX-11 DATATRIEVE now. In addition to verifying the installation,
 
           the UETP defines most of the DATATRIEVE objects used as examples 
           in the DATATRIEVE documentation set.  

           Do you wish to run the UETP for DATATRIEVE? [Y/N]:

        Answer Y if you want to run the UETP immediately.  Chapter 2 describes
        the UETP for DATATRIEVE.  The next message that the installation
        command procedure sends to the terminal is:

           VAX-11 DATATRIEVE contains support for FMS, DIGITAL's form management


           system.  There is a User Environment Test Package (UETP) which tests
           this interface with FMS.  This test may be run only if you are on one


           of the DIGITAL video terminals that is supported by FMS.  This test
           does not run on a hard-copy terminal.

           Do you wish to run the UETP for DATATRIEVE-FMS? [Y/N]:

        Answer Y if you want to run the UETP for DATATRIEVE-FMS.  Chapter 2
        describes the DATATRIEVE-FMS UETP.  The next message that the
        installation command procedure sends to the terminal is:




                                              1-11















        VAX-11 DATATRIEVE INSTALLATION PROCEDURE


           There is also a User Environment Test Package (UETP) for VAX-11 
           DATATRIEVE graphics.  This may be run if you are on a VT125
           terminal.

           Do you wish to run the UETP for DATATRIEVE graphics? [Y/N]:

        Answer Y if you wish to run the UETP for DATATRIEVE graphics.  The
        UETP for DATATRIEVE graphics is described in Chapter 2.

        If DBMS is installed, the following message is sent to the terminal:

           If you wish, you may now run the User Environment Test Package 
           (UETP) for the VAX-11 DATATRIEVE interface to VAX-11 DBMS now.

           Do you wish to run the UETP for DATATRIEVE/DBMS? [Y/N]:

        Answer Y if you wish to run the UETP for DATATRIEVE/DBMS.  The UETP
        for DATATRIEVE/DBMS is described in Chapter 2.

        The final message from the installation command procedure is:

           Installation of VAX-11 DATATRIEVE is complete.

           For best performance, the system startup file [SYSMGR]SYSTARTUP.COM
           should be modified to install the images DTRSHR.EXE and DTR32.EXE.
           This can be done by adding the following:

                   $ RUN SYS$SYSTEM:INSTALL
                   INSTALL> SYS$SHARE:DTRSHR/OPEN/SHARE
                   INSTALL> DTR32/OPEN/SHARE

           For best performance in environments where the distributed features 
           of VAX-11 DATATRIEVE is anticipated, the system startup file
           [SYSMGR]STARTUP.COM should be modified to install the image DDMF.EXE.


           This can be done by adding the following:

                   $RUN SYS$SYSTEM:INSTALL
                   INSTALL> DDMF/OPEN/SHARE



        1.5  REPLACE STANDARD CONSOLE MEDIUM

        After the installation command procedure has been completed, control
        returns to the command procedure VMSUPDATE.  If you are not making any
        further updates, respond N to the query:

           Are there any more kits to process?

        You should then restore the standard console medium to the console
        drive.  The console medium is mounted when you respond Y to the query:

           Are you ready to continue?



                                         1-12





























                                      CHAPTER 2

                            USER ENVIRONMENT TEST PACKAGES



        Four UETPs come with VAX-11 DATATRIEVE:  one to test VAX-11
        DATATRIEVE, one to test the DATATRIEVE-FMS interface, one to test the
        VAX-11 DATATRIEVE graphics capability, and one to test the
        DATATRIEVE/DBMS interface.



        2.1  THE DATATRIEVE UETP

        You can run the DATATRIEVE UETP as part of the installation procedure,
        or you can run the UETP after DATATRIEVE is installed.  To run the
        UETP after DATATRIEVE is installed, type the following commands:

           $ SET DEFAULT [SYSTEST.DTR32]
           $ RUN SYS$SYSTEM:DTR32 

           DTR> @DTR.TST

        The DATATRIEVE UETP is about 20 pages long, so the entire UETP is not
        repeated here.  You can tell that the installation is successful if
        you receive the following message at the end of the UETP:

           !
           ! The VAX-11 DATATRIEVE User Environment Test
           ! Package has completed successfully.
           !

        You have to make responses to prompts during the DATATRIEVE UETP.  The
        parts of the UETP that require a response are included here and the
        suggested responses are printed in red.











                                         2-1

















        USER ENVIRONMENT TEST PACKAGES


           !
           ! TEST STORE
           !
           ! PLEASE SUPPLY THE FOLLOWING VALUES:
           !    MANUFACTURER:  HINKLEY
           !    MODEL:        BERMUDA 40
           !    RIG:          YAWL
           !  * LENGTH-OVER-ALL: 140
           !    LENGTH-OVER-ALL: 40
           !    DISPLACEMENT:  20000
           !    BEAM:         12
           !  * PRICE:        82000 AND XX/100
           !    PRICE:        $82,000
           !    CONFIRM:      N
           !
           ! VALUES MARKED WITH "*" WILL GENERATE AN ERROR AND BE REPROMPTED
           !
           STORE YACHTS :VERIFY
           Enter MANUFACTURER: HINKLEY
           Enter MODEL: BERMUDA 40
           Enter RIG: YAWL
           Enter LENGTH_OVER_ALL: 140
           Validation error for field LENGTH_OVER_ALL.
           Re-enter LENGTH-OVER-ALL: 40
           Enter DISPLACEMENT: 20000
           Enter BEAM: 12
           Enter PRICE: 82000 AND XX/100
           Validation error for field PRICE.
           Re-enter PRICE: $82,000

                                         LENGTH
                                          OVER
           MANUFACTURER   MODEL     RIG   ALL   WEIGHT BEAM  PRICE

            HINKLEY     BERMUDA 40 YAWL   40    20,000  12  $82,000   
           DISPLAY: IF RECORD IS OK, CONFIRM WITH Y
           Enter CONFIRM: N


           !
           ! INVOKE REPORT (SUGGEST  TT:  AS OUTPUT FILE)
           !
           :LOA-REPORT
           Enter FILE: TT:












                                         2-2

















                                                USER ENVIRONMENT TEST PACKAGES


        At this point a report is sent to the terminal.  When the report
        finishes, the UETP continues:

           !
           ! INVOKE REPORT (SUGGEST  LP:  AS OUTPUT FILE)
           !
           :LOA-REPORT
           Enter FILE: LP:

        At this point a report is sent to the line printer, and the UETP
        continues:

           READY YACHTS MODIFY
           !
           ! RESPOND WITH 47 (OR SOMETHING)
           !
           MODIFY BEAM
           Enter BEAM: 47
           PRINT TYPE,BEAM

           MANUFACTURER   MODEL    BEAM

            METALMAST   GALAXY      47

           !
           ! RESPOND WITH 48 (OR SOMETHING)
           !
           MODIFY ALL BEAM
           Enter BEAM: 48
           !
           PRINT ALL BEAM

           BEAM

            48
            48
            48
            48
            48




                                                      (continued on next page)












                                         2-3

















        USER ENVIRONMENT TEST PACKAGES


           !
           ! RESPOND EACH TIME WITH 0 (PLEASE)
           !
           FOR CURRENT PRINT TYPE THEN MODIFY BEAM

           MANUFACTURER   MODEL

            METALMAST   GALAXY
           Enter BEAM: 0
            O'DAY       32
           Enter BEAM: 0
            RYDER       S. CROSS
           Enter BEAM: 0
            TA CHIAO    FANTASIA
           Enter BEAM: 0
            WRIGHT      SEAWIND II
           Enter BEAM: 0
           READY YACHTS READ
           PRINT ALL

                                          LENGTH
                                           OVER
           MANUFACTURER   MODEL     RIG    ALL   DISPLACEMENT BEAM  PRICE

            METALMAST   GALAXY     SLOOP   32        9,500     00
            O'DAY       32         SLOOP   32       11,000     00  $29,500
            RYDER       S. CROSS   SLOOP   31       13,600     00  $32,500
            TA CHIAO    FANTASIA   SLOOP   35       23,200     00
            WRIGHT      SEAWIND II SLOOP   32       14,900     00  $34,480



























                                         2-4

















                                                USER ENVIRONMENT TEST PACKAGES


        2.2  THE DATATRIEVE-FMS UETP

        You can run the DATATRIEVE-FMS UETP as part of the installation
        procedure, or you can run the UETP after DATATRIEVE is installed.  You
        can run the DATATRIEVE-FMS UETP only on a VT52 or VT100 family
        terminal.  To run the DATATRIEVE-FMS UETP after DATATRIEVE is
        installed, type the following commands:

           $ SET DEFAULT [SYSTEST.DTR32]
           $ RUN SYS$SYSTEM:DTR32 

           DTR> @DTRFMS.TST

        When VAX-11 DATATRIEVE uses FMS to print records, FMS erases the
        screen before printing the first record.  The DATATRIEVE-FMS UETP asks
        you to enter a character and press RETURN before each statement that
        causes FMS to erase the screen.  Here is a summary of the
        DATATRIEVE-FMS UETP:

        1.  The UETP sends some instructions to your terminal and waits for
            you to enter a character and press RETURN.  After you respond, the
            UETP defines three domains that use FMS:  YACHTS_FMS,
            SAILBOATS_FMS, and FAMILIES_FMS.

        2.  The UETP readies YACHTS_FMS and prints a few records without using
            FMS.  Then the UETP sends some instructions to your terminal and
            waits for you to enter a character and press RETURN.  After you
            respond, the UETP prints a record using FMS.  Press RETURN after
            FMS displays the record.

        3.  The UETP sends some instructions to your terminal and waits for
            you to enter a character and press RETURN.  After you respond, the
            UETP prints several records using FMS.  Press RETURN after FMS
            displays each record.

        4.  The UETP tests the MODIFY statement.  The UETP sends some
            instructions to your terminal and waits for you to enter a
            character and press RETURN.  After you respond, FMS displays the
            first record for you to modify.  To move the cursor from one field
            to another, use the TAB and BACKSPACE keys.  The TAB key moves the
            cursor to the next field, and the BACKSPACE key moves the cursor
            back to the previous field.  Modify only the BEAM field in each
            record.  After you modify each record, press RETURN.

        5.  The UETP tests the STORE statement.  The UETP sends some
            instructions to your terminal and waits for you to enter a
            character and press RETURN.  After you respond, FMS puts a form on
            the screen for you to fill in.  Use the TAB and BACKSPACE keys to
            move from one field to another.  If you have trouble entering an
            acceptable value for a field, position the cursor on that field
            and press the HELP key (PF2 on a VT100).  After you fill in the
            form, press RETURN.




                                         2-5

















        USER ENVIRONMENT TEST PACKAGES


        6.  The UETP tests the PRINT statement again, using the FAMILIES_FMS
            and SAILBOATS_FMS domains.  The UETP waits for you to enter a
            character and press RETURN before each PRINT statement.  After FMS
            displays the SAILBOAT_FMS records, the UETP sends the following
            message to your terminal:

               !
               ! End of DATATRIEVE-FMS User Environment Test Package
               !















































                                         2-6

















                                                USER ENVIRONMENT TEST PACKAGES


        2.3  THE DATATRIEVE GRAPHICS UETP

        If the plot definitions were loaded during the installation, you can
        run the DATATRIEVE graphics UETP.  You must use a VT125 to run the
        DATATRIEVE graphics UETP.  To run the DATATRIEVE graphics UETP, use
        the following commands:

           $ SET DEFAULT [SYSTEST.DTR32]
           $ RUN SYS$SYSTEM:DTR32 

           DTR> @DTRPLOT.TST

        The DATATRIEVE graphics UETP does not require any input from the
        terminal.  There are substantial pauses between plots.  The DATATRIEVE
        graphics UETP displays the following plots on your terminal:

        1.  WOMBAT - A picture of a wombat.

        2.  DATE-Y - A scattergraph with dates along the horizontal axis.

        3.  SHADE - The previous scattergraph is shaded.

        4.  DATE-Y - A scattergraph with dates along the horizontal axis.

        5.  CONNECT - The points in the previous scattergraph are connected.

        6.  DATE-LOGY - A scattergraph with dates along the horizontal axis
            and a logarithmic scale for the vertical axis.

        7.  LR - A linear regression line is plotted for the previous
            scattergraph.

        8.  STACKED-BAR - A bar chart with stacked bars and a legend.

        9.  MULTI-BAR - A bar chart with multiple bars and a legend.

        10.  X-Y - A simple scattergraph.

        11.  LR - A linear regression line is plotted for the previous
            scattergraph.

        12.  X-LOGY - A scattergraph with a logarithmic scale for the vertical
            axis.

        13.  HISTO - A histogram.

        14.  PIE - A pie chart.

        15.  BAR - A bar chart.

        16.  SORT-BAR - The bars of the previous bar chart are sorted by
            descending height.




                                         2-7

















        USER ENVIRONMENT TEST PACKAGES


        17.  BAR - A bar chart.

        When the DATATRIEVE graphics UETP finishes, the following message
        displays on the terminal:

           !
           ! End of User Environment Test Package for Datatrieve graphics
           !
           EXIT















































                                         2-8

















                                                USER ENVIRONMENT TEST PACKAGES


        2.4  THE DATATRIEVE/DBMS UETP

        You can run the DATATRIEVE/DBMS UETP as part of the installation
        procedure, or you can run the DATATRIEVE/DBMS UETP separately.  To run
        the DATATRIEVE/DBMS UETP after installing VAX-11 DATATRIEVE, type the
        following command:

           $ @[SYSTEST.DTR32]DTRPARTS.BLD

        If the VAX-11 DBMS monitor is not running, you receive the following
        message:

           The DBMS Monitor is not running! Do you wish to start it? [Y/N]:

        If you receive this message, you must respond Y to continue with the
        DATATRIEVE/DBMS UETP.

        The DATATRIEVE/DBMS UETP is rather long, so the entire UETP is not
        repeated here.  If the DATATRIEVE/DBMS UETP runs successfully, the
        following message is displayed:

           !
           ! End of DATATRIEVE/DBMS User Environment Test Package
           !

        You have to make responses to prompts during the DATATRIEVE/DBMS UETP.
        The parts of the UETP that require answers are included here and the
        suggested responses are printed in red.




























                                              2-9

















        USER ENVIRONMENT TEST PACKAGES


        DTR> SELECT
        DTR> PRINT

           Part                                                             Unit


          Number   -----------------Part Description----------------- St   Price

        TI-6789-01 RK HOUSING                                         G     $300


                $190  FS
        !
        ! Respond with 123 ( or something )
        !
        MODIFY PART_PRICE
        Enter PART_PRICE: 123
        PRINT PART_ID, PART_PRICE

           Part            Unit
          Number          Price

        TI-6789-01         $123

        !
        ! Respond with 321 ( or something )
        !
        MODIFY ALL PART_PRICE
        Enter PART_PRICE: 321
        PRINT ALL PART_PRICE

                Unit
               Price

                $321
                $321
                $321
                $321
                $321




                                                      (continued on next page)
















                                         2-10

















                                                USER ENVIRONMENT TEST PACKAGES


        !
        ! Respond each time with 0 ( Please )
        !
        FOR CURRENT
          PRINT PART_ID THEN MODIFY PART_PRICE

           Part
          Number

        TI-6789-01
        Enter PART_PRICE: 0
        BR-8901-23
        Enter PART_PRICE: 0
        TE-2345-67
        Enter PART_PRICE: 0
        TE-2178-90
        Enter PART_PRICE: 0
        TI-1334-56
        Enter PART_PRICE: 0
        PRINT ALL
           Part                                                             Unit


          Number   -----------------Part Description----------------- St   Price

        TI-6789-01 RK HOUSING                                         G       $0


                $190  FS
        BR-8901-23 LA36                                               G       $0


                $750  FS
        TE-2345-67 RP05                                               G       $0


              $1,900  FS
        TE-2178-90 RK06                                               G       $0


              $1,100  FS
        TI-1334-56 RP HOUSING                                         G       $0


                $300  FS























                                         2-11





























                                      CHAPTER 3

                         RELEASE NOTES FOR VAX-11 DATATRIEVE



        Changes in the release notes for this version of VAX-11 DATATRIEVE are
        found primarily in Section 3.6, Restrictions and Section 3.8,
        Differences Since VAX-11 DATATRIEVE V1.2.



        3.1  INTRODUCTION

        These release notes include:

        1.  Features of this version that were not available in DATATRIEVE-11

        2.  Incompatibilities between VAX-11 DATATRIEVE and DATATRIEVE-11

        3.  Information on the relation of performance to working set size

        4.  Omissions from other manuals in the VAX-11 DATATRIEVE
            documentation set

        5.  Restrictions on use of the software

        6.  Differences Between Versions 1.3 and 1.2

        7.  A table comparing VAX-11 DATATRIEVE data types with those of the
            CDD Data Definition Language (V2.0)

        8.  An appendix documenting the QXTR program














                                         3-1

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2  NEW FEATURES

        VAX-11 DATATRIEVE has many features not found in DATATRIEVE-11.  This
        section gives a brief description of several of these new features.



        3.2.1  The Logical Name DTR$DATE_INPUT

        DATATRIEVE translates this logical name at startup time and uses the
        result to interpret dates in character string literals.  Legal values
        are combinations of the letters M, D, and Y.  The combination you use
        determines the order of month, day, and year DATATRIEVE uses to
        interpret dates specified with numbers.  The default setting is MDY.

        For example, by default DATATRIEVE interprets 02/10/80 as February 10,
        1980.  If you define DTR$DATE_INPUT as DMY, DATATRIEVE interprets
        02/10/80 as October 2, 1980.  DATATRIEVE also interprets six-digit
        values, such as 072081, according to this order.



        3.2.2  A Third Concatenation Expression

        A third form of concatenation, triple bar concatenate, has been added
        to DATATRIEVE.  Triple bar concatenate inserts exactly one space
        between the two value strings.  The following list shows the three
        forms of concatenation in VAX-11 DATATRIEVE.  The number signs (#)
        indicate spaces.


              o  Single Bar |

                 Strings are concatenated without suppression of spaces:

                       FIRST_NAME|LAST_NAME produces JIM#####JONES#######


              o  Double Bar ||

                 All trailing spaces are stripped from the first literal:

                       FIRST_NAME||LAST_NAME produces JIMJONES#######


              o  Triple Bar |||

                 One trailing space is retained (or added to) the first
                 literal:

                       FIRST_NAME|||LAST_NAME produces JIM#JONES#######





                                         3-2

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.3  The CROSS Clause

        VAX-11 DATATRIEVE extends the record selection expression to allow
        cross products of two or more domains, collections, or lists.  A cross
        product, qualified with a Boolean, is the same as a relational
        database JOIN.  The following statements show examples of the CROSS
        clause of the rse:

           DTR> FIND YACHTS CROSS OWNERS

           DTR> FIND YACHTS CROSS OWNERS WITH OWNERS.TYPE EQ YACHTS.TYPE

           DTR> FIND X IN YACHTS CROSS Y IN OWNERS WITH Y.TYPE EQ X.TYPE

           DTR> PRINT BOAT, NAME OF YACHTS CROSS OWNERS OVER TYPE

        The CROSS clause can also be used to "flatten" hierarchies.  This
        PRINT statement shows the syntax for flattening the hierarchical
        domain FAMILIES:

           DTR> PRINT KID_NAME, AGE OF FAMILIES CROSS KIDS SORTED BY AGE



        3.2.4  The EDIT Command

        VAX-11 DATATRIEVE uses a version of the VAX-11 EDT Editor.  As in
        DATATRIEVE-11, you can use the EDIT command with a procedure name to
        edit the procedure.  However, if you invoke the Editor with the
        keyword EDIT alone on the input line, DATATRIEVE puts the previous
        command or statement in the main buffer of the Editor.  You can edit
        the command or statement to correct an error, repeat or modify the
        command or statement, insert additional commands or statements, or
        store a useful command or statement as a procedure.

        If you exit from the Editor with the EXIT command, DATATRIEVE executes
        everything in the main buffer of the Editor.  If you exit with the
        QUIT command, DATATRIEVE ignores the contents of the main buffer of
        the Editor and returns you to DATATRIEVE command level (indicated by
        the DTR> prompt).

        The Editor includes all the commands and features of the VAX-11 EDT
        Editor, except journalling.  Especially useful for applications
        development are the INCLUDE and WRITE commands, keypad editing, and
        the startup command file.











                                         3-3

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.5  SORT

        In either the SORT statement or the SORTED BY clause of the rse, an
        item in a sort-list can contain value expressions in addition to field
        names.



        3.2.6  The VAX-11 Common Data Dictionary

        VAX-11 DATATRIEVE uses the VAX-11 Common Data Dictionary (CDD) as its
        dictionary.  Unlike DATATRIEVE-11, in which each private dictionary is
        an independent RMS file, the Common Data Dictionary is a hierarchy of
        directories resembling the structure of VAX/VMS file directories.
        Each CDD directory can catalog the definitions of domains, records,
        tables, procedures, and databases.  A CDD directory can also catalog
        other directories.

        The difference between the DATATRIEVE-11 dictionary commands and those
        of VAX-11 DATATRIEVE is the form of the name you specify in the
        command.  In DATATRIEVE-11 dictionary commands you use a file
        specification to refer to a dictionary.  In VAX-11 DATATRIEVE,
        however, you specify a CDD path name to refer to a directory or object
        in the Common Data Dictionary.



        3.2.6.1  The Default Dictionary Directory

        When you invoke VAX-11 DATATRIEVE, the CDD translates the logical name
        CDD$DEFAULT.  If a translation (consisting of the full CDD path name
        of a dictionary directory or object) exists for your process, the CDD
        uses the result for the equivalent of a SET DICTIONARY command
        specifying that directory or object.  You may find it convenient to
        define CDD$DEFAULT in your VAX/VMS startup command file (LOGIN.COM).



        3.2.6.2  The SET DICTIONARY Command

        The VAX-11 DATATRIEVE SET DICTIONARY command differs from its
        DATATRIEVE-11 equivalent:  in VAX-11 DATATRIEVE you specify a CDD path
        name, rather than a file specification.  A full CDD path name has this
        form:

           CDD$TOP [(password)] [.directory_name [(password)]] [...]

        Each directory_name is the name of a CDD directory.  CDD$TOP is the
        root directory of the CDD, and is the first segment of every full
        dictionary path name.






                                         3-4

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        A relative dictionary path name does not begin with CDD$TOP and is
        interpreted relative to your default dictionary directory.  The first
        name of a valid relative path name must be the name of a directory
        cataloged in your default dictionary directory.



        3.2.6.3  The DEFINE DICTIONARY Command

        The DEFINE DICTIONARY command, like the SET DICTIONARY command,
        requires a CDD path name.  Unlike the DEFINE DICTIONARY command of
        DATATRIEVE-11, that of VAX-11 DATATRIEVE does not implicitly set your
        default dictionary directory to the one newly created.



        3.2.6.4  The SHOW PRIVILEGES Command

        The new SHOW PRIVILEGES command displays the access privileges you
        have to a dictionary directory, domain, or other dictionary object.
        The syntax format for the command is:

           SHOW PRIVILEGES [[FOR] path_name]

        The syntax element path_name is a CDD path name.  If you omit the
        path_name, this command shows your privileges to your default
        dictionary directory.



        3.2.6.5  The DEFINEP Command

        The new DEFINEP command is quite different from the DATATRIEVE-11
        DEFINEP command.  See the VAX-11 DATATRIEVE Reference Manual or enter
        HELP DEFINEP after invoking DATATRIEVE.



        3.2.7  The Startup Command File:  DTR$STARTUP

        When you invoke VAX-11 DATATRIEVE, it translates the logical name
        DTR$STARTUP.  If it is defined as a VAX/VMS file containing DATATRIEVE
        commands and statements, DATATRIEVE executes the contents of that
        file.  DATATRIEVE does not display the commands and statements on your
        terminal as it executes them.  The file can contain any valid
        DATATRIEVE commands and statements.










                                         3-5

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.8  User-defined Synonyms:  DTR$SYNONYM

        When you invoke VAX-11 DATATRIEVE, it translates the logical name
        DTR$SYNONYM.  If it is defined as a VAX/VMS file that contains
        DATATRIEVE keywords paired with their synonyms, DATATRIEVE adds the
        synonyms to the list of DATATRIEVE keywords available during that
        DATATRIEVE session.  The records in the synonym file must have this
        format:

           keyword<spaces>synonym<spaces>

        In this format, keyword is a VAX-11 DATATRIEVE keyword, <spaces> are
        one or more spaces or tabs, and synonym is a keyword synonym you want
        defined.  If you define a DATATRIEVE domain, record, and data file for
        your synonyms, you can easily maintain your list of keyword synonyms.
        You can use this record definition:

           01 PAIR.
              03 KEYWORD PIC X(20).
              03 SYNONYM PIC X(20).

        Synonyms cannot include embedded spaces.



        3.2.9  Domain Tables

        In addition to tables stored in the dictionary like the tables in
        DATATRIEVE-11, VAX-11 DATATRIEVE supports a second type of table
        called the domain table.  The syntax to define a domain table is:

           DEFINE TABLE path-name FROM [DOMAIN] domain-path-name

                [USING] code-field : translation-field [,]

                 ELSE   "translation-string"
                         translation-string 

           END_TABLE

        In this format, domain-name is the CDD path name of a domain,
        code-field and translation-field are fields in the domain, and
        translation-string is an optional character string literal that
        DATATRIEVE displays if your input value does not match any value in
        the code-field.  DATATRIEVE uses the code field as the search field
        when you refer to the table with the keywords VIA or IN followed by a
        dictionary path name of the domain table.  DATATRIEVE uses the values
        in the translation field for the output value if your input value
        matches a value in the code field.  If no match is found, DATATRIEVE
        displays the translation-string in the ELSE clause if you include one
        in the table definition.





                                         3-6

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        When you refer to a domain table in a DATATRIEVE statement and
        DATATRIEVE loads it into your workspace, DATATRIEVE lists it as a
        domain table in the table list when you enter a SHOW READY command.
        You can change the READY access mode of a loaded domain table with the
        READY command.  By default, domain tables are readied with shared read
        access.



        3.2.10  Additions to Dictionary Tables

        You can now specify edit strings and query-headers for the values in
        DATATRIEVE dictionary tables.  The syntax for these clauses is the
        same as the syntax for the corresponding field definition clauses.



        3.2.11  Miscellaneous Syntax Changes

        You can use single and double quotation marks to enclose character
        string literals.  If you include quotation marks of one type in a
        character string literal enclosed by the other type, you do not have
        to repeat the ones in the literal for DATATRIEVE to display them.  If
        the exterior quotation marks are the same as the interior, you must
        repeat the ones in the literal for DATATRIEVE to display them.

        You can start numbers with a decimal point.  You cannot, however, end
        a number with a decimal point.



        3.2.12  Qualified Field Names

        In VAX-11 DATATRIEVE, you can qualify a field name with the name of
        the associated domain.  The qualified field names in the second of the
        following FOR statements are valid in VAX-11 DATATRIEVE:

           DTR> FOR YACHTS
           DTR> FOR OWNERS WITH OWNERS.TYPE EQ YACHTS.TYPE
           DTR> ...
















                                         3-7

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.13  Missing Values

        VAX-11 DATATRIEVE has general support for "missing values." A missing
        value is a value stored in a field to denote "no value for this item"
        rather than its actual value.  For example, in the YACHTS domain, the
        value 0 in the PRICE field means that the price was not available, not
        that the boat is free.



        3.2.13.1  The MISSING VALUE Clause

        You can specify a missing value by including the MISSING VALUE clause
        in a field definition or in a variable declaration.  The syntax format
        for the MISSING VALUE clause is:

           MISSING [VALUE] [IS] literal

        In this clause, "literal" is a literal expression.  Unless you define
        a DEFAULT VALUE for a field or variable, DATATRIEVE uses the missing
        value to initialize the field when you store a record and do not
        assign a value to a field, or to initialize the variable when you
        declare it.



        3.2.13.2  The MISSING Relational Operator

        You can use the MISSING relational operator in an rse to find records
        that contain the missing value in a field without knowing what that
        missing value is.  This PRINT statement shows the use of the MISSING
        relational operator:

           DTR> PRINT YACHTS WITH PRICE MISSING

        If you have not defined a missing value for a field, DATATRIEVE uses
        as the missing value a zero or a space, depending on the data type of
        the field.



        3.2.13.3  Missing Values in Statistical Functions

        When you use the statistical functions AVERAGE, MAX, MIN, TOTAL,
        RUNNING TOTAL, and STD_DEV, VAX-11 DATATRIEVE skips all records in
        which the function's value expression contains a missing value.  If
        DATATRIEVE skips any records when doing a statistical calculation, it
        displays a warning message showing the number of records used in the
        calculation and the total number of records in the target record
        stream.






                                         3-8

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.13.4  Edit string for Missing Values

        You can also specify an edit string for fields and variables with
        declared missing values.  The format of the missing edit string is:

           <edit-string-1>?<edit-string-2>

        If the value of the field or variable does not equal the missing
        value, DATATRIEVE uses the first edit string to format the display of
        the value.  If the value of the field or variable does equal the
        missing value, DATATRIEVE uses the second edit string to format the
        display of the value.  This PRINT statement shows the use the missing
        value edit string:

           DTR> PRINT TYPE, PRICE USING $$$,$$$?'*MISSING*'



        3.2.14  The DEFAULT VALUE Clause

        You can also include a DEFAULT VALUE clause in a field definition or a
        variable declaration to control the initial value of that field or
        variable.  The syntax for the clause is:

           DEFAULT [VALUE] [IS] literal

        This field definition shows the use of a DEFAULT VALUE clause:

           03 DATE-IN USAGE DATE DEFAULT VALUE IS 'TODAY'.



        3.2.15  FROM Value Expressions

        The new FROM value expression lets you refer to a field of a domain as
        a source of values.  The syntax format of the FROM value expression
        is:

           value-expression FROM rse

        In the FROM expression, value-expression is any DATATRIEVE value
        expression, and rse is a record selection expression.  DATATRIEVE
        computes the value by the following algorithm:


             1.  DATATRIEVE finds the first record in the record selection
                 expression.

             2.  If DATATRIEVE finds a record, it determines the value of the
                 value expression in the context of that record.

             3.  If no record satisfies the rse, DATATRIEVE aborts the current
                 statement.



                                         3-9

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.16  The DROP Statement

        The new DROP statement removes the selected record from a collection.
        The slot for that record remains in the collection, but the dropped
        record is ignored for all further processing of the collection.



        3.2.17  Extensions to the SELECT Statement

        The SELECT statement now includes the position option PRIOR and a WITH
        clause containing a Boolean expression.  The new syntax format is:

                FIRST
                NEXT
        SELECT  PRIOR             [collection-name] [WITH boolean-expression]
                LAST
                value-expression

        If you use a Boolean expression in the WITH clause, DATATRIEVE selects
        the next (prior or last) record in the collection with that value.
        When you use a Boolean expression in a SELECT LAST statement,
        DATATRIEVE starts, in effect, at the end of the collection and
        searches backward.  When you use a Boolean expression in a SELECT NEXT
        WITH or SELECT PRIOR statement, DATATRIEVE starts at the currently
        selected record in the collection and searches forward for NEXT or
        backward for PRIOR.



        3.2.18  The RUNNING TOTAL and RUNNING COUNT Statistical Functions

        VAX-11 DATATRIEVE supports the statistical functions RUNNING TOTAL and
        RUNNING COUNT.  The formats for these functions are:

           RUNNING TOTAL value-expression

           RUNNING COUNT

        DATATRIEVE computes the value of each of these each time the function
        is evaluated.  Unlike the other statistical functions, RUNNING TOTAL
        and RUNNING COUNT are computed "on the fly" and are not reset when you
        use them in AT BOTTOM statements in the Report Writer.  Like TOTAL,
        RUNNING TOTAL ignores missing values.



        3.2.19  The Standard Deviation Function

        You can now also use the statistical function, standard deviation.
        The syntax of the function is:

           STD_DEV value-expression [OF rse]



                                         3-10

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.20  The EXTRACT ALL Command

        The EXTRACT command now allows you to use the keyword ALL instead of a
        list of dictionary objects when you want to move or back up all the
        contents of a dictionary directory.  You can put the ON
        file-specification clause either before or after the list of
        dictionary objects you want to extract.



        3.2.21  New Edit strings

        Edit strings can now contain character string literals that you
        enclosed in quotation marks.  The edit string in this PRINT statement
        contains the character string literal " and a bargain":

           DTR> PRINT ALL TYPE, PRICE USING $$$,$$$' and a bargain'

        You can also express numbers in scientific notation with an edit
        string of the following form:

           <mantissa edit-string>E<exponent edit-string>

        This PRINT statement shows an example of the exponential edit string:

           DTR> PRINT 12.345 USING -.9(5)E-9(2)

            .12345E 02

        The new edit string for missing values is discussed in Section 3.2.13.



        3.2.22  The SET SEARCH Command

        Another SET option, SET SEARCH, is available to simplify traversing
        database sets and lists in hierarchical records.  When SET SEARCH is
        in effect and DATATRIEVE encounters in a PRINT statement a field name
        for which it has no valid context, it searches for a possible context
        for that field.  For hierarchical records DATATRIEVE searches
        sub-lists;  for VAX-11 DBMS domains, DATATRIEVE searches all records
        belonging to sets in which the target record is a tenant.  In either
        case, if DATATRIEVE finds a context for the field, it constructs any
        inner print lists required to resolve the context.

        This feature is potentially dangerous because DATATRIEVE cannot tell
        the difference between a genuine error and the intentions of a person
        avoiding complex syntax.  Consequently, the feature can be controlled
        with the SET SEARCH and the SET NO SEARCH commands.  SET SEARCH
        enables the feature, and SET NO SEARCH disables it.  The default
        setting when you invoke DATATRIEVE is SET NO SEARCH.





                                         3-11

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.23  The READY Command

        The READY command now allows you to ready more than one domain in a
        single command and to specify an "alias" or alternate domain name.
        The READY command also allows you to access domains on remote nodes in
        a network of VAX computers linked by DECnet Phase III.  The syntax
        format of the READY command is:

           READY   path-name [AT network-address] [AS alias]

                          PROTECTED   READ                      [,...]
                   [FOR]  SHARED      WRITE
                          EXCLUSIVE   MODIFY
                                      EXTEND

        The "path-name" is a CDD path name of a domain definition and "alias"
        is the temporary, substitute name you use to refer to the domain.  The
        "network-address" has these forms:

            node-name     node-name["username password"]

        These examples show the new extensions of the READY command:

           DTR> READY YACHTS FOR WRITE, OWNERS FOR SHARED READ

           DTR> READY YACHTS AT WOMBAT"DTR32 DEMO" AS FRIBBLE FOR MODIFY



        3.2.24  The VAX-11 DATATRIEVE Call Interface

        The VAX-11 DATATRIEVE Call Interface Manual describes how to call
        VAX-11 DATATRIEVE from any VAX/VMS language.



        3.2.25  User-defined Functions

        You can also extend VAX-11 DATATRIEVE with user-written or VAX-11
        Run-Time Library string and numeric functions.  You must define the
        global name, DATATRIEVE name, data type, and calling sequences when
        DATATRIEVE is installed on your system or is relinked.  The procedure
        for defining and linking user-defined functions is described in the
        VAX-11 DATATRIEVE Call Interface Manual.  Some functions are included
        with VAX-11 DATATRIEVE.  Those are described in Chapter 9 of the
        VAX-11 DATATRIEVE Reference Manual.










                                         3-12

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.26  The Keyword USAGE and the USAGE Clause

        The keyword USAGE is now optional for field definitions.

        In addition to COMP, COMP-1, COMP-2, COMP-3, and COMP-5, DATATRIEVE
        recognizes BYTE, WORD, LONG, QUAD, PACKED, REAL, DOUBLE, and DATE.
        All but PACKED can be used without a picture string.  COMP-6 is not
        supported on VAX/VMS.

        Scale factors can be implied through the use of PICTURE strings or
        specified explicitly by a SCALE clause.  The following two field
        definitions are equivalent:

           03 FOO PIC S999V99 USAGE COMP.

           03 FOO LONG SCALE -2.



        3.2.27  The PLOT Command

        VAX-11 DATATRIEVE includes a PLOT statement that is described in the
        VAX-11 DATATRIEVE Graphics Notebook.  To use DATATRIEVE Graphics, you
        must have a VT125 terminal.



        3.2.28  The Distributed Data Manipulation Facility

        VAX-11 DATATRIEVE supports remote domains to give you access to data
        residing on other VAX computers connected to your system by DECnet
        Phase III.  The syntax format to define a domain on a remote node is:

           DEFINE DOMAIN path-name USING domain-path-name
              AT network-address 
              [FORM [IS] form-name [IN] form-library];

        In this command, path-name is the CDD path name of the local domain
        you are defining, domain-path-name is the CDD path name of the domain
        at the remote node, and network-address is the name of the remote node
        and the optional access control information (in the form "username
        password", including the quotation marks).  This example shows a
        remote domain definition:

           DTR> DEFINE DOMAIN REMOTE_PARTS USING 
           CON> CDD$TOP.INVENTORY.PARTS_DOMAIN AT PARTVX"HOWL FRED";
           DTR>

        In this example, the domain being defined in the local default CDD
        directory is REMOTE_PARTS.  The actual data, however, resides in a
        DATATRIEVE domain on the VAX system PARTVX.  The CDD path name of the
        domain on PARTVX is CDD$TOP.INVENTORY.PARTS_DOMAIN.




                                         3-13

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        When you ready a remote domain, DATATRIEVE establishes a DECnet link
        to the remote system, and spawns a DATATRIEVE Remote Server (the
        Distributed Data Management Facility or DDMF).  If the remote domain
        definition includes access control information ("username password"),
        the DDMF process is created under that account, and the VAX/VMS
        startup command file (LOGIN.COM) is executed.  However, during the
        DATATRIEVE initialization, the DATATRIEVE startup file DTR$STARTUP is
        not executed.  Once DATATRIEVE is initialized, the DDMF acts as an
        agent for the DATATRIEVE image on your local system.

        Generally, you can use remote domains like other domains (RMS, DBMS,
        and views), but they are subject to a number of restrictions (see
        Section 3.6).



        3.2.29  VAX-11 DATATRIEVE Support for VAX-11 FMS

        You can specify a form name and form library in a domain definition.
        This is the syntax format of the FORM clause:

           FORM [IS] form-name [IN] form-library

        The argument form-library is the file name of an FMS library, and
        form-name is the name of a form in that form library.  This example
        shows a domain definition that includes a clause:

           DTR> DEFINE DOMAIN YACHTS USING YACHT
           CON> FORM IS YACHT1 IN DTRFMS.FLB;
           DTR>

        When you access a domain containing a form definition, DATATRIEVE uses
        the form for:

              o  Output when you enter a PRINT statement with no print list.

              o  Input when you enter a STORE statement without a USING
                 clause.

              o  Input when you enter a MODIFY statement without a field list
                 or a USING clause.

        DATATRIEVE uses the first six characters of the record definition
        field name as the corresponding FMS field name.  Any field name not
        common to the record definition and form definition is ignored.  The
        designer of the form has the responsibility of ensuring that the FMS
        and DATATRIEVE field lengths and types are compatible.

        You control the use of FMS forms with the SET FORM and SET NO FORM
        commands.  If SET NO FORM is in effect when you ready a domain,
        DATATRIEVE ignores the form defined for that domain until the domain
        is finished.  If SET FORM is in effect when you ready the domain, you
        can control the use of the form on a statement-by-statement basis with
        SET FORM and SET NO FORM commands.


                                         3-14

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.30  VAX-11 DATATRIEVE Support of VAX-11 DBMS

        VAX-11 DATATRIEVE supports transparent access to data stored by VAX-11
        DBMS.  However, DATATRIEVE provides more complete access to DBMS
        features through extensions to the DATATRIEVE language that allow
        explicit set walking, connecting, disconnecting, and reconnecting to
        sets, rolling back and commiting changes, and storing records in a
        particular set occurrence.  You can print, store, and modify DBMS
        records.  The ERASE statement, however, is not permitted for DBMS
        domains.  The VAX-11 DATATRIEVE/DBMS Interface Manual contains
        information on using this interface;  the manual is included in the
        VAX-11 DBMS documentation set.



        3.2.31  LIST Statement

        The new DATATRIEVE statement, LIST, is a variation of the PRINT
        statement.  The LIST statement displays specified fields in a vertical
        format, rather than in a horizontal one as the PRINT statement does.
        The LIST statement is useful when you want to display a large number
        of fields for each detail line.  Unlike the PRINT statement, LIST is
        restricted to the display of fields;  you cannot use LIST to display
        constants or expressions.  This example shows the way the LIST
        statement displays two records from the hierarchical domain FAMILIES:

           DTR> FIND FIRST 2 FAMILIES
           [2 records found] 
           DTR> LIST ALL

           FATHER      : JIM       
           MOTHER      : ANN       
           NUMBER_KIDS :  2
               KID_NAME    : URSULA    
               AGE         :  7
               KID_NAME    : RALPH     
               AGE         :  3

           FATHER      : JIM       
           MOTHER      : LOUISE    
           NUMBER_KIDS :  5
               KID_NAME    : ANNE      
               AGE         : 31
               KID_NAME    : JIM       
               AGE         : 29
               KID_NAME    : ELLEN     
               AGE         : 26
               KID_NAME    : DAVID     
               AGE         : 24
               KID_NAME    : ROBERT    
               AGE         : 16





                                         3-15

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.2.32  The SHOW SET_UP Command

        The new SHOW SET_UP command displays the status of five other SET
        options:  COLUMNS_PAGE, [NO] ABORT, [NO] PROMPT, [NO] SEARCH, and [NO]
        FORM.



















































                                         3-16

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.3  COMPATIBILITY WITH DATATRIEVE-11

        Every attempt has been made to keep VAX-11 DATATRIEVE compatible with
        DATATRIEVE-11, yet consistent with the growth of the product in the
        VAX/VMS environment.  There are, however, a number of
        incompatibilities that can cause difficulties if you convert
        DATATRIEVE-11 applications to VAX-11 DATATRIEVE.  This section lists
        the important differences between the two products.



        3.3.1  Field Alignment

        By default, DATATRIEVE-11 uses an alignment rule called LEFT_RIGHT
        that aligns all COMP, COMP-1, and COMP-2 fields on even address
        boundaries.  The LEFT_RIGHT rule is also used by COBOL-11 and
        COBOL-74.  VAX-11 DATATRIEVE, however, uses a rule called MAJOR_MINOR
        to determine address boundary alignment.  Unless a record definition
        contains a SYNC clause, the MAJOR_MINOR rule never generates padding
        fields when computing field offsets within a record definition.  The
        MAJOR_MINOR rule is also used by VAX-11 COBOL.

        To allow data to be shared between versions of DATATRIEVE, both
        DATATRIEVE-11 V2.0 and VAX-11 DATATRIEVE have the ALLOCATION clause in
        the record definition, immediately preceding the top-level field.
        Both products give you the option of specifying LEFT_RIGHT or
        MAJOR_MINOR.  VAX-11 DATATRIEVE also gives an option of
        ALIGNED_MAJOR_MINOR allocation.

        If the ALLOCATION clause is present in a record definition, it takes
        precedence over the default alignment rule for either DATATRIEVE
        implementation.

        To help you convert applications from DATATRIEVE-11 to VAX-11
        DATATRIEVE, the QXTR program is supplied with your VAX-11 DATATRIEVE
        kit.  QXTR extracts the contents of an entire DATATRIEVE-11 dictionary
        into a command file.  QXTR inserts the clause ALLOCATION IS LEFT_RIGHT
        in any record definition that does not contain an ALLOCATION clause.
        At command level in VAX-11 DATATRIEVE, you can generally invoke the
        command file produced by QXTR without having to change it.

        A description of QXTR is included as an appendix to this document.














                                         3-17

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.3.2  Dictionary Commands

        The dictionary protection commands (DEFINEP, SHOWP, DELETEP) differ
        greatly between DATATRIEVE-11 and VAX-11 DATATRIEVE.  The VAX-11
        Common Data Dictionary supports more levels of protection than does
        the DATATRIEVE-11 dictionary, and the CDD offers a rich syntax for
        granting and denying privileges.  All the access privileges available
        from the CDD and DATATRIEVE can be manipulated with DATATRIEVE's
        DEFINEP, SHOWP, and DELETEP commands.

        The SET DICTIONARY command for VAX-11 DATATRIEVE requires a CDD path
        name.  The DATATRIEVE-11 DICTIONARY command requires a file name.
        DATATRIEVE-11 recognizes the SET DICTIONARY command to be a return to
        the default dictionary.  You can perform the equivalent operation in
        VAX-11 DATATRIEVE with the command, SET DICTIONARY CDD$DEFAULT.



        3.3.3  DEFINE DICTIONARY

        Following execution of a DATATRIEVE-11 DEFINE DICTIONARY command,
        DATATRIEVE-11 does the equivalent of a SET DICTIONARY to the new
        dictionary.  VAX-11 DATATRIEVE does not.



        3.3.4  Underscore and Hyphen

        In names, DATATRIEVE-11 considers the underscore and hyphen as
        distinct characters.  Hence, DATATRIEVE-11 treats the names FLD-1 and
        FLD_1 as different strings.

        VAX-11 DATATRIEVE, however, considers a hyphen in a name to be a
        lowercase underscore.  In VAX-11 DATATRIEVE, therefore, FLD-1 and
        FLD_1 are two instances of the same name, just as it considers FLD-1
        and fld-1 to be two instances of the same name.



        3.3.5  Invalid Picture Strings

        Although both VAX-11 DATATRIEVE and DATATRIEVE-11 tolerate illegal
        PICTURE strings in field definitions, the results are not always
        compatible.  For example, the following field definition is illegal,
        but tolerated:

           03 ITEM PIC 99.99.

        The decimal point is not a valid PICTURE string character in either
        product.  DATATRIEVE-11 treats the sample field as a 5-character text
        field;  VAX-11 DATATRIEVE, however, treats it as a 4-digit numeric
        field with a scale factor of -2.  DATATRIEVE-11 record descriptions
        that contain illegal picture strings must be converted manually to
        work in VAX-11 DATATRIEVE.


                                         3-18

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.3.6  Spaces in Numeric Data

        VAX-11 DATATRIEVE produces a warning message when it encounters a
        field declared as numeric that contains a non-numeric digit (most
        commonly a space).  DATATRIEVE-11, on the other hand, does not
        validate fields that are declared as numeric.  The most common sources
        of invalid characters are:

              o  Invalid PICTURE strings from DATATRIEVE-11

              o  Numeric redefinitions of alphanumeric fields

              o  Programs written in other languages

        Programs written in native mode VAX languages generally produce valid
        numeric data.



        3.3.7  Leading Spaces in Dictionary Tables

        DATATRIEVE-11 handles numeric fields in dictionary tables
        inconsistently.  In general, it retains leading zeros for numeric
        strings, and truncates leading zeros for computed values.  VAX-11
        DATATRIEVE always truncates leading zeros.  Consequently, you must
        revise DATATRIEVE-11 dictionary tables to remove leading zeros when
        converting them for use with VAX-11 DATATRIEVE.





























                                         3-19

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.4  TUNING VAX-11 DATATRIEVE PERFORMANCE

        Two important factors control system performance when using VAX-11
        DATATRIEVE:


              o  Image installation

              o  User working set quotas




        3.4.1  Installing the VAX-11 DATATRIEVE Images as Shareable

        VAX-11 DATATRIEVE software is very large;  if the person who installs
        it does not take care to install it correctly, it is possible to
        overload the physical memory on a VAX/VMS system and cause poor system
        performance.

        The images comprising VAX-11 DATATRIEVE (SYS$SHARE:DTRSHR.EXE and
        SYS$SYSTEM:DTR32.EXE) must be installed with the /SHARE option.
        Failure to do so causes each process running VAX-11 DATATRIEVE to have
        a private copy of these images.  The absence of sharing causes
        extensive swapping on all but the largest of VAX systems.  If VAX-11
        DATATRIEVE is installed with the /SHARE option, however, all users
        share a single copy of these images.





























                                         3-20

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.4.2  Adjusting Working Set Quota

        VAX-11 DATATRIEVE is sensitive to the VAX/VMS working set quota
        parameter.  The system manager establishes this parameter for each
        user and enters it in the authorization file.  It controls the maximum
        working set size that a user can have.  If the quota is set low,
        excessive page faulting occurs and adversely affects performance for
        both that user and the system.  For optimal system performance, the
        working set quota for VAX-11 DATATRIEVE users should be at least 350.

        The graph in Figure 3-1 shows system performance as a function of user
        working set quota.  The data is based on measurements of executing the
        VAX-11 DATATRIEVE User Environment Test Package (UETP) on a VAX/VMS
        V2.3 system with various settings of the working set quota parameter.


        Figure 3-1:  System Performance versus Working Set Quota







































                                         3-21

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.5  DOCUMENTATION OMISSIONS AND CHANGES

        This section points out features of VAX-11 DATATRIEVE either omitted
        from the other manuals or added to the product after the other manuals
        were printed.



        3.5.1  Exponential Constants

        VAX-11 DATATRIEVE supports numeric constants of this form:

           <mantissa>E<exponent>

        This format expresses a numeric value in exponential or floating point
        form.  An exponential constant is a value expression, and you can use
        it in VAX-11 DATATRIEVE statements.  You can also use it to respond to
        prompts for data.  The numeric literal used as the exponent must be an
        integer.  The mantissa can include digits to the right of the decimal
        place.  Spaces are not allowed.  Both the exponent and the mantissa
        can include a leading sign.

           Examples:    234E56    -234E4    234e-5    2.34E+05

        Because the value of the exponential constant is often outside the
        normal range of numbers (up to 32 digits), this format should be used
        with elementary fields or variables with a floating point data type:
        REAL, COMP-1, COMP-2.  The values should ordinarily be displayed with
        a floating point edit string, such as -ZZZ.99E-999.



        3.5.2  BEFORE and AFTER Keywords

        BEFORE and AFTER are DATATRIEVE keywords you can use in Boolean
        expressions.  They are especially useful for comparing dates.

        BEFORE is a synonym for LESS_THAN:

            DTR> FIND PROJECTS WITH ACTUAL BEFORE EXPECTED

        AFTER is a synonym for GREATER_THAN:

            DTR> ERASE ALL OF PROJECTS WITH ACTUAL AFTER EXPECTED












                                         3-22

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.5.3  Selected Records in Sorted Collections

        If you select a record in a collection and then sort that collection,
        the collection no longer has a selected record, and the single record
        context for the selected record no longer exists.  The following
        example shows the effect of a SORT statement on a selected record:

        DTR> FIND FIRST 10 YACHTS
        DTR> SELECT 5
        DTR> SORT BY BEAM
        DTR> SHOW CURRENT
        Collection CURRENT 
            Domain: YACHTS 
            Number of Records: 10 
            No Selected Record 
            Sort order: BEAM 



        3.5.4  Additional Entry Point to Callable Interface

        The new entry point, DTR$PRINT_DAB, aids program development.  Your
        program calls DTR$PRINT_DAB with the address of the DATATRIEVE Access
        Block (DAB) as the only argument.  The routine prints the contents of
        the various fields of the DAB on SYS$OUTPUT.  Your program can call
        this subroutine at any point during execution.  The subroutine has no
        effect on the state of DATATRIEVE.



        3.5.5  Collection Size

        Limits for the size of DATATRIEVE collections are:

              o  Limit for RMS files:  1,301,264 Records

              o  Limit for DBMS files:  979,776 Records

        The limit for collections formed by joining two domains with a CROSS
        clause is about one half the number of records for each of the file
        types listed above.  The limit for collections joining three domains
        is about one third the number of records, and so on.














                                         3-23

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.6  RESTRICTIONS

        This section lists the restrictions on the use of VAX-11 DATATRIEVE.



        3.6.1  Call Interface Options

        The DATATRIEVE Access Block options DAB$V_REPROMPT_ENABLE and
        DAB$V_DEBUG have no effect.  VAX-11 DATATRIEVE reprompts for
        conversion errors, overflows, and validation failures regardless of
        the state of the REPROMPT_ENABLE bit.  Both bits are undefined and
        reserved for future use by VAX-11 DATATRIEVE.



        3.6.2  Forms

        The following restrictions affect the use of FMS forms with
        DATATRIEVE:

              o  Describing the Fields on Your Form

                 Field names are limited to six characters, an FMS
                 restriction.  These six characters must be unique and match
                 the first six characters of the field names in your
                 DATATRIEVE domain.  If any hyphens are in the DATATRIEVE
                 field name, you should define them as underscores to FMS
                 because DATATRIEVE converts all hyphens to underscores when
                 it puts names into uppercase.

              o  Multiple Page Forms

                 Forms that span multiple pages are not supported.  This is an
                 FMS restriction.

              o  Scrolled Areas

                 Forms cannot contain scrolled areas.  DATATRIEVE does not
                 know which areas are scrolled and which are not.  There is no
                 homogeneous method of applying scrolling to all fields, so it
                 is not done at all.

              o  Query Names

                 DATATRIEVE does not use query names to match FMS field names.
                 It uses only the field name.

              o  Edit Strings

                 DATATRIEVE edit strings are never used to display fields on a
                 form.  Format fields using simple conversion to string.




                                         3-24

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


              o  Date Fields

                 Define date fields in FMS as PIC X(11).  You may enter the
                 date in any of the usual DATATRIEVE formats, but it is always
                 displayed in the default format:  DD-MMM-YYYY.

              o  Default Values

                 DATATRIEVE default values always override FMS defaults.

              o  Hierarchical Domains and Views

                 You can use a form with a hierarchical domain or view.  You
                 can find examples of how to structure such a form in the form
                 library SYS$SYSROOT:[SYSTEST.DTR32]DTRFMS.FLB.  The forms
                 FAMIL and SAIL use the domains FAMILIES and SAILBOATS,
                 respectively.

              o  Fixed Decimal Numeric Fields

                 When defining a numeric field in DATATRIEVE as fixed decimal,
                 define the field with a V or a decimal point (for example,
                 99V99 or 99.99).  In FMS, define the field as 99.99, with
                 fixed decimal, right justify, clear character 0, and
                 zero-fill attributes.

              o  Numeric Keyboard

                 On a STORE or MODIFY statement that uses a form, DATATRIEVE
                 leaves the numeric keypad in application mode to provide a
                 way to exit.  This restricts the use of the numbers on the
                 keypad.

              o  Entering Signed Decimal Numeric Data through FMS

                 Because of a restriction in FMS, you cannot enter signed
                 decimal numeric data through FMS forms.

              o  Using FMS from a Calling Program

                 Refer to Chapter 2 of the Call Interface Manual for an
                 explanation of the use of FMS from a calling program.

              o  Using SET FORM/SET NO FORM

                 If you ready a domain with SET FORM in effect, you can change
                 to SET NO FORM without readying the domain again.  If you
                 ready a domain with SET NO FORM in effect, you must FINISH,
                 SET FORM, and READY the domain in order to use the form.

              o  Remote Forms

                 Your form and form library must be defined and reside on the



                                         3-25

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


                 local node to be used by DATATRIEVE.  You cannot use your
                 form to display groups of remote records using PRINT ALL.
                 You can, however, display, store, and modify single remote
                 records.

              o  Type_ahead and nolowercase

                 If you set your terminal to type_ahead or nolowercase, it may
                 not work when using FMS forms.  When you type ahead to an FMS
                 form, FMS can miss the termination of the terminal
                 identification escape sequence.  If this happens, all input
                 from your terminal is read and discarded.  If you set your
                 terminal to nolowercase, FMS never sees the termination of
                 the terminal identification escape sequence, since the
                 sequence ends with a lowercase letter.  In either case,
                 CTRL/Y is the only escape.

              o  Terminating Execution while Using a Form

                 You must type a CTRL/C followed by <RETURN> to terminate the
                 execution of a PRINT statement that uses a form.  The CTRL/C
                 tells DATATRIEVE that you want to stop the PRINT operation,
                 but DATATRIEVE has no way to tell FMS.  Pressing <RETURN>
                 gives control back to DATATRIEVE and allows DATATRIEVE to
                 stop execution.

                 You can use two methods to terminate the execution of a STORE
                 or MODIFY statement.  On a VT100 terminal, you can press the
                 minus key on the keypad.  That stops processing of the form
                 and returns you to the DTR> prompt.  On any terminal, you can
                 press CTRL/C followed by <RETURN> to end processing.  Note
                 that this works only when you are positioned to an
                 alphanumeric field.




        3.6.3  Remote Domains

        The following restrictions affect the use of remote domains with the
        Distributed Data Manipulation Facility (DDMF):

              o  You cannot use FMS forms to display groups of records from
                 remote domains.  You can use forms to store data into a
                 remote domain and to display a selected record, or a record
                 from a collection or record stream containing no other
                 records.

              o  The CONTAINING operator does not work with a prompt for
                 remote domains.  For example, the following PRINT statement
                 does not work:

                      DTR> PRINT REMOTE_YACHTS WITH BUILDER CONTAINING *.BUILDER



                                         3-26

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


                 DATATRIEVE uses a fixed-length field to transmit the prompt
                 value to the Remote Server, and it fills the field with
                 spaces.

              o  You cannot use a Boolean expression containing the relational
                 operators IN or ANY in a record selection expression with a
                 remote domain or collection as its source.

              o  You cannot use a remote domain or collection in a CROSS
                 clause.

              o  You cannot use qualified field names to differentiate fields
                 that have the same name and are part of the same record
                 definition.  If you plan to use a record definition for
                 remote access, give each field a unique name.

              o  Distributed DATATRIEVE does not reprompt for validation
                 errors.  A validation error causes the statement being
                 processed to abort.

              o  You cannot store or modify hierarchical records in remote
                 domains.  If a remote domain contains a sublist, MODIFY and
                 STORE statements can refer only to those fields in the record
                 that are not lists.

              o  In a record selection expression with a remote domain as its
                 source, you cannot use a Boolean expression that contains a
                 computation involving the remote data.  The following PRINT
                 statement violates this restriction:

                       DTR> PRINT REMOTE_YACHTS WITH PRICE GT DISP*3

                 By contrast, these PRINT statements are legal:

                       DTR> PRINT REMOTE_YACHTS WITH PRICE = 15000

                       DTR> PRINT REMOTE_YACHTS WITH PRICE GT DISP


              o  You cannot use a WHILE statement that contains statements
                 that access remote data.




        3.6.4  RMS Key Optimization

        Use BETWEEN instead of GREATER_THAN...LESS_THAN for searches on RMS
        keys.  If you use BETWEEN, DATATRIEVE reads exactly the number of
        records required.  If you use GREATER_THAN...LESS_THAN, DATATRIEVE
        chooses which key it will optimize on.  For example:

          DTR> PRINT YACHTS WITH BUILDER BETWEEN "ALBERG" AND "PEARSON"



                                         3-27

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        is faster than

          DTR> PRINT YACHTS WITH BUILDER GREATER_THAN "ALBERG" AND
          CON> BUILDER LESS_THAN "PEARSON"

        DATATRIEVE-11 optimizes the GREATER_THAN...LESS_THAN case, but VAX-11
        DATATRIEVE does not.



        3.6.5  DBMS Optimization

        DATATRIEVE tries to use SORTED and CALC sets when you specify the
        following Booleans:

              o  FIELD1 EQ VALUE1

              o  (FIELD1 EQ VALUE1) AND (FIELD2 EQ VALUE2)

              o  (FIELD1 EQ VALUE1) AND any other Boolean

        DATATRIEVE does not optimize the following Booleans:

              o  NOT (Boolean)

              o  (Boolean) OR (Boolean)

              o  Any Boolean not using the EQUAL relation




        3.6.6  Recursive Procedures

        The use of recursive procedures is unsupported.  They may cause wrong
        answers, access violations, and excessive use of CPU time at the
        termination of the recursion, and they are very expensive to detect.
        The following example shows an invalid construct that appears to work,
        although it does not:

        PROCEDURE FOO
        SET ABORT
        DECLARE A PIC X.
        A = *."an option (A,B)"
        IF A = "A" THEN PRINT "option A"
        IF A = "B" THEN PRINT "option B"
        :FOO
        END_PROCEDURE








                                         3-28

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.6.7  Inter-Domain Validation and Virtual Expressions

        Inter-domain validation (VALID IF) and virtual (COMPUTED BY)
        expressions are order-dependent.  If you have a domain that references
        another domain, the domain being referenced must be readied first.
        This means, of course, that it is impossible to have two domains that
        reference each other, since both would have to be readied first.

















































                                         3-29

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.7  USAGE NOTES

        This section contains information on:

              o  Using VAX-11 DATATRIEVE from a DCL command file

              o  Doing arithmetic in VAX-11 DATATRIEVE

              o  Joining a domain against itself

              o  Using remote domains




        3.7.1  Using VAX-11 DATATRIEVE from a DCL Command File

        You can use DATATRIEVE from a DCL command file as if you were invoking
        it in the usual way.  Call this file LENGTH.COM:

           $DEFINE SYS$INPUT TT
           $MCR DTR32 EXECUTE YACHT_PRINT

        The procedure YACHT_PRINT readies the YACHTS domain and prints any
        yachts with LOA equal to a figure you specify at your terminal when
        running the command file:

           $@LENGTH
           Enter LOA: 25

                                       LENGTH
                                        OVER
           MANUFACTURER   MODEL     RIG    ALL   WEIGHT BEAM  PRICE
            CAPE DORY   25         SLOOP   25     4,000  07   $8,995
            DUFOUR      25         SLOOP   25     2,700  08
            IRWIN       25         SLOOP   25     5,400  12  $10,950
            SALT        19         SLOOP   25     2,600  07   $6,590




        3.7.2  Very Long Input Lines

        VAX-11 DATATRIEVE has a limit of 255 characters to an input line.  If
        you have an input line that is difficult to break up into multiple
        lines, you can put part of the text in a procedure and use the
        procedure invocation instead of the text.  For example, you might want
        to avoid typing:

           PRINT Q1 USING $$$,$$$,$$9.99, Q2 USING $$$,$$$,$$9.99,
           Q3 USING $$$,$$$,$$9.99, Q4 USING $$$,$$$,$$9.99

        You can define the following procedure:



                                         3-30

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


           DEFINE PROCEDURE US_ES
           USING $$$,$$$,$$9.99
           END_PROCEDURE

        You can then replace the line with:

           PRINT Q1 :US_ES, Q2 :US_ES, Q3 :US_ES, Q4 :US_ES




        3.7.3  Arithmetic Accuracy

        When doing arithmetic, DATATRIEVE tries to give you the accuracy you
        request.  The following examples show how you can get the accuracy you
        need for a given equation.  In the first example, no number of decimal
        places is specified:

           DTR> DECLARE FOO PIC 99.
           DTR> FOO = 12 / 7
           DTR> PRINT FOO

           FOO

           02

        Since FOO has no decimal places, the value of FOO is the rounding of
        the calculation's result.  You can force decimal places in two ways.
        First, you can put an edit string on the calculation and DATATRIEVE
        uses the number of places requested by the edit string.  Second, you
        can add trailing zeros to one of the values in the calculation.
        DATATRIEVE uses the larger number of places in printing the answer:

           DTR> PRINT 12 / 7 USING 9.9999
           1.7143
           DTR> PRINT 12.0000 / 7
           1.7143

        If you don't force the number of decimal places in a calculation, you
        will get the default of 3 places.  For example:

           DTR> PRINT 12 / 7
              1.714

        There is a limit, determined by the datatype, for the number of
        decimal places you can force in a calculation.  When a calculation
        would cause an overflow the operands are scaled, causing zeros in the
        least significant places of the result.  In the example, note that the
        requested number of decimal places are displayed, but several of the
        least significant are zero.

           DTR> PRINT 12.000 / 7.00000000000
              1.71428500000



                                         3-31

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.7.4  Field Name Resolution on a CROSS

        If you join a domain against itself, it is very difficult to access
        the fields.  DATATRIEVE prints misleading results.  For example, in
        domain FOOS with field FOO:

           FOO

            1
            2
            3

           DTR> PRINT FOOS CROSS FOOS

           FOO FOO

            1   1
            2   2
            3   3
            1   1
            2   2
            3   3
            1   1
            2   2
            3   3

        Both FOO fields are from the same domain, although they use different
        records.  DATATRIEVE cannot tell them apart.  You should ready the
        domain twice, using an alias the second time:

          DTR> READY FOOS AS BARS
          DTR> PRINT FOOS CROSS BARS

           FOO FOO

            1   1
            1   2
            1   3
            2   1
            2   2
            2   3
            3   1
            3   2
            3   3

        If you formed a collection of the cross, you could reference the
        fields by qualifying the field name with the domain name:

           DTR> FIND FOOS CROSS BARS
           DTR> PRINT ALL FOOS.FOO, BARS.FOO






                                         3-32

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.7.5  Remote DBMS Domains

        DATATRIEVE has a limit of one subschema at a time, whether the
        subschema is remote or local.  Most of the time, DATATRIEVE prints an
        error if you try to ready a second subschema:

                  One subschema already in use - can't ready domain.

        In one case, DATATRIEVE does not properly detect the attempt to use a
        second subschema:  when the name of the subschema at one remote node
        duplicates the name of the subschema at a second remote node.  If this
        happens, the internal data structures at the local node can become
        corrupt and cause unexpected results.

        When using a remote domain, you are limited to data types that can be
        expressed in the DATATRIEVE language, which is used to communicate
        across the network.  When you use a VAX data type DATATRIEVE cannot
        understand, you receive the message:

                           Feature is not yet implemented.




































                                         3-33

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.8  DIFFERENCES SINCE VAX-11 DATATRIEVE V1.2

        This section contains information on the differences between this
        version of DATATRIEVE and the previous version.



        3.8.1  Callable DATATRIEVE

        There are several changes pertaining to the Call Interface.  These
        involve the varying string class of descriptors and blank
        substitutions.



        3.8.1.1  Varying String Descriptors

        The varying string (VS) class of descriptors using the varying text
        (VT) datatype is accepted for passing strings through the call
        interface.  If these strings are used for the message buffer or
        auxiliary buffer in the DAB, then they must be preextended to their
        maximum length before they are passed to the DTR$INIT call.  That is,
        the current length (CURLEN) field should be the same as the maximum
        string length (MAXSTRLEN) field.  The CURLEN field is ignored by
        DATATRIEVE after the DTR$INIT call.  The related DAB field, either
        DAB$W_MSG_LEN or DAB$W_AUX_LEN, must be referenced to determine the
        actual length of the string returned by DATATRIEVE.



        3.8.1.2  Blank Substitutions

        When you use a "!CMD" command substitution parameter in a call to
        DTR$COMMAND, and the string you pass to DTR is only blanks, it no
        longer causes errors.



        3.8.2  Repair of Date Bugs

        Several bugs with dates are repaired.



        3.8.2.1  Missing Values for Dates

        Missing values for dates now work properly.  You can specify a missing
        value on a date, and use that missing value in the edit-string.  For
        example:







                                         3-34

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE



            DTR> DECLARE FOO DATE MISSING VALUE 0 
            CON>    EDIT_STRING DD-MMM-YYYY?"At Last".
            DTR> PRINT FOO

                 FOO

               At Last




        3.8.2.2  Date Arithmetic

        Date arithmetic now works as documented in the reference manual.  Date
        addition and subtraction are valid, but assymetric operations;  date
        multiplication and division are not permitted.  The result of addition
        of a date to another number is that date plus the number of days.  To
        subtract days you must add negative days.  If you subtract a number
        from a date, the number is converted to a date and the difference in
        days is the result.



        3.8.2.3  Optimizing the Conversion from Text to Dates

        Dates are no longer considered constants.  In previous versions, all
        dates were considered constants and the conversion from text to date
        was factored out of loops.  This usually showed up as odd behavior
        with the use of "NOW".  For example:

            DTR>  WHILE 1 = 1 PRINT FN$TIME ("NOW")

                   FN$TIME

        13:04:37.42
        13:04:37.42
        13:04:37.42
         . . .

        Now it works as expected:


                   FN$TIME

        13:04:37.42
        13:04:37.43
        13:04:37.44
         . . .







                                         3-35

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.8.3  Standard Deviation is Fixed

        The formula we were using to calculate the standard deviation was
        incorrect.  We now apply Bessel's correction to the standard
        deviation.



        3.8.4  Limits Increased

        In previous releases, you could not create more than 10 nested FOR
        loops.  The limit has been increased to 32.  This limit applies to
        other looping structures as well, such as CROSS.

        Also, there was a limit of approximately 55 readied domains (including
        those used in views), found collections and temporary collections
        (such as those generated during a sort).  The limit has been increased
        to 250.




        3.8.5  Adding or Changing Domains with Key Fields

        As of DATATRIEVE V1.2, a repair was made that fixed several problems.
        When you had an outer loop that was using RMS keyed access and an
        inner loop that did a STORE or MODIFY on that same domain, several
        problems might occur.  You might see the same record more than once,
        you might miss some records you should have seen or you might see the
        same record an infinite number of times.  The repair for this is that
        DATATRIEVE creates a temporary collection of all of the records that
        will be involved in the record stream before performing the FOR loop.
        This way you see every record you should see exactly once.  Take the
        following case:

            FOR A IN FOOBARS WITH ALTERNATE_KEY GE "FRIBBLE"
                            MODIFY USING ALTERNATE_KEY = "GRUMBLE"

        In versions prior to V1.2, that statement would cause you to see the
        record once with the alternate key FRIBBLE and once with the alternate
        key GRUMBLE.  This no longer happens.



        3.8.6  OCCURS DEPENDING

        The DEPENDING ON field may now be a virtual field calculated with the
        COMPUTED BY clause.








                                         3-36

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.8.7  Optimization of the OR Boolean.

        Prior to this version, if you used an OR of two keyed fields, both
        keys were used.  This could sometimes cause duplicate records.  In
        this version, we still use both keys, but you no longer get duplicate
        records.  For example:

            PRINT YACHTS WITH BUILDER = "PEARSON" OR MODEL = "26"

        The result was that the PEARSON 26 boat was displayed twice.  Now it
        is displayed only once.



        3.8.8  Retrieving Domain Tables from the CDD

        Prior to this version, you could not use qualified field names in
        defining a domain table if the field names had different levels of
        qualification.  For example, this table is defined properly, but
        DATATRIEVE could not retrieve it from the dictionary.

            DEFINE TABLE FOO FROM YACHTS USING
                BOAT.TYPE.BUILDER : SPECS.PRICE
            END_TABLE

        This problem is fixed.



        3.8.9  Recursive Virtual Expressions

        Recursive virtual expressions are now trapped, instead of causing
        access violations.  You now get the following error message:

            DTR> DECLARE A COMPUTED BY A + 1.
            DTR> PRINT A
            Field "A" contains a self-reference and can not be evaluated.




        3.8.10  Report Writer

        Several bugs have been repaired:

              o  Some occurrences of the NEW_PAGE print element would cause
                 multiple new pages to be printed.  At other times, no new
                 page would be printed when it should have been.  Some of
                 these cases remain as restrictions.  Others have been
                 repaired.






                                         3-37

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


              o  Problems with formatting narrow reports have been fixed.




        3.8.11  Ports

        You can no longer declare global ports with duplicate names.  Also,
        you can reready ports to different access modes.



        3.8.12  Miscellaneous


              o  Many error messages have been changed to make them more
                 informative and understandable to DATATRIEVE users.

              o  The default floating point edit-string is:  -9.9999E+99

              o  File specifications may now contain hyphens in either the
                 directory specification ([-.SOMEPLACE]) or as negative
                 version numbers (FOO.BAR;-2).

              o  Domain tables of views now work without fail.

              o  Sorting by calculations that cause scaling has been repaired.





























                                         3-38

















                                           RELEASE NOTES FOR VAX-11 DATATRIEVE


        3.9  VAX-11 DATATRIEVE DATA TYPES

        With few exceptions, data types are equivalent for VAX-11 DATATRIEVE
        and the Common Data Dictionary Data Definition Language (available in
        CDD V2.0).  Table 3-1 lists both sets of keywords.  It also supplies
        the page number in the ^&VAX-11 DATATRIEVE Reference Manual\& where
        the usage of each word is described.

















































                                         3-39

















        RELEASE NOTES FOR VAX-11 DATATRIEVE


        Table 3-1: VAX-11 DATATRIEVE Data Types


                                                                    USAGE
        CDD (V2.0) KEYWORD             DATATRIEVE KEYWORD         REFERENCE

        BYTE                           BYTE                         11-49
        WORD         May be signed     WORD           Signed only   11-49
        LONGWORD     or unsigned       LONGWORD                     11-49
        QUADWORD                       QUADWORD                     11-49
        OCTAWORD                       --
        F_FLOATING                     REAL                         11-50
        D_FLOATING                     DOUBLE                       11-50
        G_FLOATING                     --
        H_FLOATING                     --
        COMPLEX                        --
        UNSIGNED NUMERIC               PIC 9(n)                     11-38
        LEFT OVERPUNCHED NUMERIC       PIC S9(n) SIGN LEADING       11-38
        LEFT SEPARATE NUMERIC          PIC S9(n) SIGN LEADING       11-38
                                         SEPARATE
        RIGHT OVERPUNCHED NUMERIC      PIC S9(n) SIGN TRAILING      11-38
        RIGHT SEPARATE NUMERIC         PIC S9(n) SIGN TRAILING      11-38
                                         SEPARATE
        PACKED NUMERIC                 PIC 9(n) PACKED              11-38
        ZONED NUMERIC                  PIC S9(n) ZONED              11-38
        BIT                            --
        DATE                           DATE                         11-50
        TEXT                           PIC A(n), PIC X(n)           11-40
        UNSPECIFIED                    PIC X(n) name FILLER         11-9
        VARIANT                        REDEFINES                    11-44
        VARYING STRING                 --
        COMPUTED BY DATATRIEVE         COMPUTED BY                  11-17
        DEFAULT_VALUE FOR DATATRIEVE   DEFAULT VALUE                11-19
        EDIT_STRING FOR DATATRIEVE     EDIT_STRING                  11-20
        MISSING_VALUE FOR DATATRIEVE   MISSING VALUE                11-33
        --                             PICTURE                      11-38
        QUERY-HEADER FOR DATATRIEVE    QUERY_HEADER                 11-42
        QUERY_NAME FOR DATATRIEVE      QUERY_NAME                   11-43
        VALID FOR DATATRIEVE IF        VALID IF                     11-52
        ALIGNED                        ALLOCATION                   11-15
        ARRAY                          --
        BASE                           --
        DIGITS ... FRACTIONS           SCALE n                      11-46
        INITIAL_VALUE                  --
        OCCURS                         OCCURS n TIMES               11-35
        OCCURS ... DEPENDING         * OCCURS n TO m TIMES          11-37
                                         DEPENDING ON 
        SCALE                          SCALE n                      11-46

        * Note especially Restriction 1, p. 11-38.






                                         3-40





























                                      APPENDIX A

                       QXTR: THE DATATRIEVE-11 EXTRACT PROGRAM



        You can use QXTR to create a command file containing all the
        definitions extracted from a DATATRIEVE-11 data dictionary.  QXTR
        allows you to extract those definitions in a form that lets you add
        them to the VAX-11 Common Data Dictionary (CDD) by executing the
        command file.  When the definitions are in the CDD, you can use them
        with VAX-11 DATATRIEVE.

        QXTR is the equivalent of an EXTRACT ALL utility for DATATRIEVE-11
        dictionaries.  It asks you for three pieces of information:

             1.  The file specification of the dictionary to be processed

             2.  Whether you want to extract the password tables for each
                 dictionary object

             3.  The name of the output command file (The default is QXTR.CMD
                 in your default directory.)

        The output of this program is an RMS sequential file that may be used
        as an indirect command file for DATATRIEVE.

        Just as with the EXTRACT command in DATATRIEVE, each dictionary object
        definition is preceded with a DELETE command.  This program also adds
        an ALLOCATION LEFT__RIGHT clause if no ALLOCATION clause is specified
        for record definitions.

        QXTR checks that you have READ privilege for the objects in the
        dictionary before extracting them.  If you do not, a message is
        printed that the object was not extracted and the program continues.
        If you are logged in under a privileged account (with a UIC of [1,x]),
        you can extract everything regardless of the password table.  If the
        password table allows only password access and not UIC/PPN access, you
        must run QXTR from a privileged account to extract the element.  On
        VAX/VMS, the UIC checked against the password table entry is the UIC
        of the account under which you logged in.  On other systems, the UIC
        checked against the password table is your current UIC.

        QXTR aborts if it encounters a corrupt dictionary element.  Determine



                                         A-1

















        QXTR: THE DATATRIEVE-11 EXTRACT PROGRAM


        which element caused the abort and delete it from the dictionary
        before running QXTR again.






















































                                         A-2

